Skip to Content
CLILogin

Authentication

Before any almyty command works in a terminal, it needs to know who you are. You sign in once, in your browser, and every almyty command on that machine uses the same sign-in. For example, npx @almyty/auth login on your laptop, and from then on almyty agents list shows your organization’s agents. This page is for people using the CLI; in the app you just sign in as usual.

Behind the scenes, signing in saves an API key (a long secret string that proves who you are, like a password for programs) to one file, ~/.almyty/credentials.json, which all almyty CLI packages read.

@almyty/auth CLI help

Browser login (interactive)

The default login flow opens your browser, authenticates via your almyty account, and mints a long-lived API key:

$ npx @almyty/auth login

Step by step:

  1. The CLI starts a temporary local HTTP server on a random port.
  2. Your default browser opens {frontend}/cli-login?callback=...&success=...&state=..., where callback is the local server and state is a one-time value the CLI generated.
  3. You sign in (or create an account) at app.almyty.com.
  4. The page posts the minted token back to the local callback along with state. The token travels in a POST body, never in a URL, and a callback carrying the wrong state is refused.
  5. The CLI writes the token to ~/.almyty/credentials.json (mode 0600) and shuts down the local server.

If you are already logged in to almyty in your browser, the flow completes in under two seconds.

Token login (CI / scripts)

Pass a pre-generated API key directly. This skips the browser entirely:

$ npx @almyty/auth login --token almyty_3f9c...

Make one in the app under Settings → API keys (click New API key, give it a name and optionally an expiry date; the key is shown once), with a logged-in CLI on another machine, or with POST /auth/api-keys (see API keys). Use this method in CI pipelines, Docker containers, and automation scripts. Revoke a key on the same Settings page.

Login without an auto-opening browser

When the CLI cannot open a browser for you, use --no-browser. It prints the same login URL and waits:

$ npx @almyty/auth login --no-browser
 
  almyty login
  Open your browser to authenticate (auto-opening if available):
    https://app.almyty.com/cli-login?callback=http%3A%2F%2F127.0.0.1%3A54312%2Fcb&success=http%3A%2F%2F127.0.0.1%3A54312%2Fsuccess&state=8f2c...
 
  Waiting for you to complete login in your browser…

The callback parameter points at the temporary server on 127.0.0.1, so the browser you open the URL in has to be able to reach that port on the machine running the CLI. On a remote box, forward it first (ssh -L 54312:127.0.0.1:54312 host) or skip the browser entirely and use --token with an API key.

Staging and self-hosted environments

Override the backend and frontend URLs when authenticating against a non-production instance:

$ npx @almyty/auth login --api https://api.staging.almyty.com --frontend https://app.staging.almyty.com

The URLs are saved in the credentials file so subsequent CLI calls use the same environment. You can also set them globally with environment variables (see below).

Logout and identity

# Remove stored credentials
$ npx @almyty/auth logout
 
# Show the currently authenticated user and environment
$ npx @almyty/auth whoami
Logged in as alice@example.com
Organization: acme
API: https://api.almyty.com

Credentials file

The credentials file lives at ~/.almyty/credentials.json with file mode 0600 (readable only by the owner). Its structure:

{
  "url": "https://api.almyty.com",
  "token": "almyty_3f9c...",
  "email": "alice@example.com",
  "frontendUrl": "https://app.almyty.com"
}

All almyty CLI packages (@almyty/skills, @almyty/agents, @almyty/chat, @almyty/mcp-server) read this file. Authenticate once and they all work.

Environment variable overrides

Environment variables take precedence over the credentials file. This is useful for CI, Docker, and per-session overrides:

VariableDescriptionDefault
ALMYTY_TOKENAPI key or JWT tokenRead from credentials file
ALMYTY_URLBackend API URLhttps://api.almyty.com
# One-liner for CI
$ ALMYTY_TOKEN=almyty_3f9c npx @almyty/skills install @acme/petstore
 
# Export for the session
$ export ALMYTY_TOKEN=almyty_3f9c
$ export ALMYTY_URL=https://api.staging.almyty.com
$ npx @almyty/skills list

When ALMYTY_TOKEN is set, the CLI never reads the credentials file at all.

Troubleshooting

”Not authenticated” errors

If any CLI prints Not authenticated, it means neither the environment variable nor the credentials file contains a valid token. Run:

$ npx @almyty/auth login

401 Unauthorized

The token exists but the server rejected it. Common causes:

  • Expired token. API keys do not expire by default, but JWTs do. Re-run npx @almyty/auth login to get a fresh key.
  • Wrong environment. Your credentials file points at production but you are trying to reach staging, or vice versa. Check with npx @almyty/auth whoami and re-login with --api if needed.
  • Revoked key. The key was revoked (DELETE /auth/api-keys/:keyId). Run npx @almyty/auth login again, or mint a new key.

Wrong environment

If whoami shows the wrong URL, log out and re-login with the correct environment:

$ npx @almyty/auth logout
$ npx @almyty/auth login --api https://api.staging.almyty.com --frontend https://app.staging.almyty.com

File permission errors

The credentials file must be owned by your user with mode 0600. If you see permission errors:

$ chmod 600 ~/.almyty/credentials.json

Browser does not open

On some Linux desktop environments, xdg-open may not be configured. Use --no-browser and open the URL manually.

OverviewAgents