cimplify login

Authorize the CLI to talk to your Cimplify business. The default flow is browser-first OAuth Authorization Code + PKCE on a loopback redirect: no key paste, no shell history, no phishing surface. `--api-key` is the headless / CI escape hatch.

Browser-first flow (default)

cimplify login

The CLI starts a one-shot HTTP server on a free loopback port, opens https://app.cimplify.io/cli/authorize?... in your default browser, and waits for the callback. You sign in (or are already signed in), click Authorize, and the CLI receives the auth code on the loopback URL. It then exchanges the code for an access token using the PKCE verifier it generated locally.

After verification the token + business context are written to ~/.config/cimplify/auth.json (mode 0600). Subsequent commands read from this file automatically.

What "browser-first" means

Step	What happens
1	CLI generates a PKCE pair (code verifier + SHA-256 challenge) and a CSRF state token.
2	CLI starts an HTTP server bound to `127.0.0.1:<random-port>`.
3	CLI calls `POST /v1/auth/cli/start` with the challenge + redirect URI; gets back an approval URL.
4	CLI opens your default browser to the approval URL.
5	You click Authorize in the browser. Cimplify redirects to the loopback URL with `?code=...&state=...`.
6	CLI verifies `state`, posts `{ auth_code, code_verifier }` to `POST /v1/auth/cli/token`, and gets back the access token.
7	CLI stores the token + your account / business in `~/.config/cimplify/auth.json`.

SSH / no-browser

On a remote machine, pass --no-browser. The CLI prints the approval URL; copy it into a browser on a machine that can reach the loopback URL.

cimplify login --no-browser

CI / headless: --api-key

For non-interactive environments (CI, container builds), pass an API key directly. Keys start with dk_ (developer) or sk_ (server). Generate them in the Cimplify dashboard.

# CI: set CIMPLIFY_API_KEY in your secret store, then:
cimplify login --api-key "$CIMPLIFY_API_KEY"

Prefer the browser flow for local development. --api-key is meant for unattended runs only; the OAuth path is shorter-lived, scoped, and revocable.

Flags

Flag	Description
(none)	Default; opens the browser.
`--no-browser`	Print the URL instead of opening it. Useful over SSH.
`--api-key <dk_...>`	Skip the browser. Authenticate with a developer or server key.
`--base-url <url>`	Override the API host. Reads `CIMPLIFY_API_URL`; defaults to `https://api.cimplify.io`.

whoami & logout

# Show the current account + business
cimplify whoami

# Forget saved credentials
cimplify logout

logout deletes ~/.config/cimplify/auth.json. The token on the server side stays valid until it expires or you revoke it from the dashboard.

Where credentials live

Path	Contents
`~/.config/cimplify/auth.json`	Access token, base URL, account ID, business ID, email, name, saved-at.
mode	`0600`. Readable only by you.

Troubleshooting

Symptom	Cause / fix
"OAuth state mismatch"	CSRF guard tripped, likely a stale tab. Re-run `cimplify login`.
Browser doesn't open	Run with `--no-browser`, then copy the printed URL into any browser.
"Loopback callback timed out"	Authorization expired; start over. The window defaults to a few minutes.
CI uses a wrong key	Ensure the key starts with `dk_` or `sk_`.

Where next

deploy Push and ship after login.
env cimplify env push --scope=preview
API keys When to use dk_ vs sk_.
CLI overview Full subcommand index.

cimplify login

On this page