The first step is to get logged in. You will need an account on an instance of the Conch API. Please work with an admin and get all squared away. Make sure you can log into the web UI before continuing here.
A new profile is be created via:
conch profile new --name <profile name> --user email@example.com
You can provide your password via the
--password argument. Otherwise, you
will be prompted for your password.
For Joyent employees, this will attempt to log you into the production instance.
If you'd like to use staging, provide the
--environment=staging argument. For
development or non-Joyent users, provide
--url=https://joyent.example.com, adjusting the URL as appropriate for your
conch profile new --name <profile name> --user firstname.lastname@example.org --environment=staging
conch profile new --name <profile name> --user email@example.com --environment=development --url http://localhost:5000
Password authentication credentials expire rather rapidly, on the order of 30 days. If you do not use the shell for 30 days, you may receive an "unauthorized" error message. To log back in, simply execute
conch profile relogin
You will be prompted for your password.
Sometimes, you might be forced to change your password, usually because you
requested a password reset or an admin reset your password. Typically, you will
receive an "unauthorized" message. You should try to
relogin and will then be
prompted to change your password.
An API token is a special piece of information that allows automation or other tools to use your Conch account without needing your actual user name or password.
Probably the best reason to use API tokens is that in the future, tokens will be the only way to use the shell. At some point, password authentication will go away. So why not get ahead of the curve?
Tokens also provide a really nice way to control access to your account. For instance, you could create a token for each device you have. If that device is lost, you can revoke only that token, cutting off access for the lost device but not impacting any others.
Further, API tokens generally don't expire for a long time. They're designed for use by automation and it'd be very silly to make someone log back in manually every now and then on every server. Once you've got an API token, you can mostly put authentication out of your mind.
Also, as we'll see shortly, it's possible to use conch with no on-disk configuration. That option is only available when using tokens.
For now, we'll stick to the basics of API tokens. A lot more documentation can be found over here
Just as a note, tokens are obfuscated inside the config file. It is not possible to use the value recorded there in any other tool.
Once you've created a profile using a password, you can easily upgrade that profile to token auth.
conch profile upgrade
This command generates a new token specifically for your local device and switches the profile to use it. No further action is required on your part.
If you already have a token (either from the web UI or
conch user tokens new,
you can create a profile from scratch using:
conch profile new --name <profile name> --token <token>
Other modifiers like
--environment are accepted as well.
If you have a token, it is possible to use the shell without ever creating a profile. There are two ways to work without a profile.
First, provide the token via the environment.
export CONCH_TOKEN='1234....' conch profile ls
Second, provide the token on the command line.
conch --token='1234....' profile ls
It is possible to have as many profiles as you want. Developers typically have one for production, one for staging, and one for their local development environment. Each profile must have a unique name but they are created just as above.
You can switch between profiles by running:
conch profile set active <profile name>
or you can override the active profile by using:
conch -p <profile name>