Authentication
The CLI supports two authentication methods: OAuth Device Flow (recommended) and manual API token entry.
Device Flow login
The recommended way to authenticate. Run the login command and the CLI will open your browser to authorize:
shipchart auth login- 1. The CLI displays a verification URL and a user code.
- 2. Your browser opens to the Shipchart authorization page.
- 3. Confirm the code matches, then approve access.
- 4. The CLI receives a token automatically and saves it to your config file.
Tip: If the browser doesn't open automatically, copy the displayed URL and open it manually.
Manual token login
If you prefer to paste an API token directly (e.g. on a headless server), use the --token flag:
shipchart auth login --tokenYou'll be prompted to paste your token. Generate one in Settings → API Tokens on the Shipchart web app.
Checking auth status
Verify you're authenticated and see which user is logged in:
shipchart auth statusLogging out
Remove the stored token from your local config:
shipchart auth logoutConfig storage
The CLI stores your authentication token and settings in:
~/.shipchart/config.jsonThis file contains your API token and any saved preferences (like default project). It is created automatically on first login.
Environment variables
You can override the config file with environment variables. These take precedence over stored settings:
| Variable | Description |
|---|---|
SHIPCHART_TOKEN | API token. Overrides the stored token from config.json. |
SHIPCHART_API_URL | Override the API base URL. Useful for development or self-hosted instances. |
# Use a specific token for a one-off command
SHIPCHART_TOKEN=your_token shipchart dashboard