Skip to main content

Authentication

The CLI needs an API token to communicate with Envshed. There are two ways to authenticate.

Run the login command and follow the browser flow:

terminal
envshed login

This will:

  1. Open your browser to the Envshed authorization page
  2. Ask you to approve the CLI access
  3. Save the token to the OS keychain, or to ~/.envshed/config.json where there is no keychain (details)

If you're not logged into Envshed in the browser, you'll be redirected to sign in first, then brought back to the authorization page.

Custom API URL​

If you're running Envshed locally or on a custom domain:

terminal
envshed login --api-url http://localhost:3005

Token-based login​

If you already have an API token (created in the web dashboard under Settings > API Tokens):

terminal
envshed login --token-stdin < token.txt

At a terminal, --token-stdin asks with a masked prompt instead. Either way, the token never appears on the command line or in your shell history. See envshed login.

Token lifetime​

A personal token, including the one envshed login saves, stops working after 30 days without use. Every request restarts the count, so a token you use keeps working. When one stops, run envshed login again. A token created through the API with an expiresAt date also stops on that date.

Verify authentication​

Check who you're logged in as:

terminal
envshed whoami

Managing tokens​

terminal
envshed token show                         # Show current token (masked)
envshed token clear                        # Remove saved token
envshed token set --token-stdin < token.txt  # Save a token you already have

Service tokens (CI/CD)​

For automated systems like CI/CD pipelines, Kubernetes, or other infrastructure, use service tokens instead of personal API tokens. Service tokens are tied to an organization (not a user), support scoped permissions, and continue working even if the creating user leaves the org.

terminal
# Create a read-only token scoped to a project, expiring in 90 days
envshed token create-service \
  -o my-org \
  -n "GitHub Actions CI" \
  -s project \
  --project-id <uuid> \
  -p read \
  --expires-in 90

You can also create and manage service tokens from the dashboard under Organization > Service Tokens.

See Service Tokens for full documentation.

Report a problem with this page