Getting Started with Hatcher

Installing Hatcher

Installing with edm

To install hatcher into an EDM-managed Python environment, simply run the following from within the desired environment:

$ edm install hatcher

Installing with pip

To install hatcher into a Python environment not managed by EDM, run:

$ pip install hatcher

First steps

Specifying an Enthought Deployment Server

When running Hatcher, the first thing to keep in mind is that it always needs to know the URL of an Enthought Deployment Server (EDS). The -u or --url option of the hatcher command is used to specify the root EDS URL:

$ hatcher -u ...


All options to the hatcher command support being passed as environment variables. The environment variable for any option is named HATCHER_<option>, where <option> is the long name for the option in upper case. For example HATCHER_URL for the --url option.


All commands in this documentation assume that the EDS URL is passed through the environment variable.

Handling self-signed SSL certificates

If the Enthought Deployment Server is using SSL and the certificate is invalid (e.g. it is a self-signed certificate or for a different domain than the server is using), the --insecure (or -k) option is required to prevent SSL connection errors.


The --insecure option should only be used if the Enthought Deployment Server is trusted.

Authenticating to Enthought Deployment Server

Password Authentication

Enthought Deployment Server requires users to be authenticated in order to perform any actions. The simplest authentication method is password authentication. This can be used by passing the --username (or -U) option to hatcher. Hatcher will prompt the user for the password when needed. There is a --password option to pass the option, but this is not considered secure as the password is then easily readable by other processes through Hatcher’s command line arguments.

$ hatcher --username ...

Password authentication always takes precedence over API token authentication, even if the username/password is passed via environment variables and the token via command line.

Token Authentication


API tokens can only be used to control access to Enthought’s own deployment server (including customer-controlled repositories that are hosted by Enthought), not to customers’ on-site deployment servers.

Enthought Deployment Server (EDS) provides token-based authentication in addition to password authentication. This first requires that the user create an API token for EDS (using password authentication); then the token is stored and used for future authentication attempts. When a token is created, a user-recognizable name is provided so that the user is able to view all tokens associated with the account. Tokens can be revoked at any time when they are no longer needed and will never be re-generated by the server.

Creating tokens

To create a new token, use the api-tokens create command:

$ hatcher -U api-tokens create user-laptop-token
Created API token user-laptop-token: 'eyJhbGciOiJIUzI1NiJ9.eyJpZCI6Nn0.qm4S4mapPYQrYeUfEZ51JVx7iKY6G_LJIg_utIqvBiQ'


The api token should be treated as private and never shared. It provides the same level of access to EDS as authenticating with a username and password. The benefit of a token is that it can be easily revoked at any time.

Using tokens

The token value can be copied and used in scripts via the --token (or -t) option or placed in the HATCHER_TOKEN environment variable to enable automatic token-based authentication:

$ hatcher -U api-tokens list
Name              | Created                    | Last Used
user-laptop-token | 2014-10-20T17:30:07.956240 |

$ hatcher --token <token-data> api-tokens list
Name              | Created                    | Last Used
user-laptop-token | 2014-10-20T17:30:07.956240 | 2014-10-20T17:31:31.224082

$ export HATCHER_TOKEN=eyJhbGciOiJIUzI1NiJ9.eyJpZCI6Nn0.qm4S4mapPYQrYeUfEZ51JVx7iKY6G_LJIg_utIqvBiQ
$ hatcher api-tokens list
Name              | Created                    | Last Used
user-laptop-token | 2014-10-20T17:30:07.956240 | 2014-10-20T17:32:33.329669
Revoking tokens

To delete a token that is no longer required, the following can be used:

$ hatcher api-tokens delete user-laptop-token

Following token deletion, if attempting to authenticate using the token, authentication will fail and the user will need to use a different token or switch to password authentication:

$ hatcher --token <token-data> api-tokens list
Authentication failed