login: Authenticating with and saving Concourse targets

The first thing you'll want to do is authenticate with your target. This is done with the login command. This is also useful to save targets under a more convenient alias, so you don't have to type out the URL all the time:

The login command serves double duty: it authenticates with a given endpoint, and saves it under a more convenient name. The name and token are stored in ~/.flyrc (though you shouldn't really edit the file manually).

Concourse deployments can be occupied by multiple teams. To specify the team to which to log in, specify the --team-name or -n flag. If not specified, this defaults to main.

So, to log in to a team my-team an endpoint served at https://ci.example.com and save it as the more convenient name example, you would run:

$ fly --target example login --team-name my-team \
    --concourse-url https://ci.example.com

The login command will see which authentication methods are available for the specified team and prompt you to choose one. For basic auth, it will ask your username and password and use them to acquire a token. For OAuth, it will give you a link to click, and after you've gone through the OAuth flow it will print an OAuth token on the page that you can then then copy and paste into the prompt.

Note that if no authentication methods are configured (e.g. when targeting a concourse/lite Vagrant box), fly will acquire a token without any prompting. You can then use the alias like normal.

In any case, a token is saved in your ~/.flyrc, which will expire after one day.

If your Concourse uses SSL but does not have a certificate signed by a trusted CA, you can use the --ca-cert flag so that fly can trust the connection, like so:

$ fly -t example login -c https://ci.example.com --ca-cert ./ca.crt

This will read the value out of the file ./ca.crt and save it into ~/.flyrc so you don't have to pass it on every login invocation.

After you've logged in you can use --target example (or -t example for short) to run a command against the saved target example. For eample, fly -t example builds will list the last few builds on the example Concourse instance.

The -t flag is intentionally stateless and must be explicitly added to each command. This reduces the risk of accidentally running a command against the wrong environment when you have multiple targets defined.