Get Started
Sign in
Sign in to the SignatureAPI CLI with a device code, choose the organization, and choose where the sign-in is stored.
The CLI acts for one SignatureAPI account: the organization you choose when you sign in. It uses a device sign-in, so you approve it in a browser on any device, not only the machine running the CLI.
You rarely need to sign in by hand. Every command that needs an account signs in on its own when there is no sign-in yet. Run login when you want to sign in ahead of time, or after logout to switch account or organization.
login
npx signatureapi login
Open the verification URL
The CLI prints a verification URL and a user code. In a terminal on macOS or Linux, it also opens the URL in your browser.
Approve the sign-in
Sign in with your SignatureAPI account, check that the code matches, and choose the organization the CLI acts for.
Done
The CLI stores the sign-in and prints the account it acts for, as its acc_ ID.
The code is valid for a limited time. If it expires before you approve it, the command fails with authorization-expired; run it again to get a new code.
login keeps a sign-in that still works and reports already_logged_in. When the stored sign-in can no longer get a token (it expired or was revoked), login starts a new sign-in and replaces the stored one once it succeeds.
| Option | Description |
|---|---|
--credential-store <store> | Where the sign-in is kept: keychain or file. Defaults to the OS keychain when one is usable, else a private file. |
--json | Print newline-delimited JSON events instead of text. See Output and exit codes. |
Sign in without a terminal
Without a terminal, such as in a container, a CI job, or a coding agent, the CLI does not open a browser. It prints the verification URL and code, then waits until a person approves them. With --json, they arrive as an authorization_required event, so an agent can show them to you:
{"type":"authorization_required","verification_uri":"https://...","user_code":"ABCD-EFGH"}
Approve the sign-in once. Later commands reuse the stored sign-in and refresh it on their own.
Where the sign-in is stored
The CLI stores its sign-in, never an API key, in one of two places:
| Store | Location | Use it for |
|---|---|---|
keychain | The OS keychain or credential manager. | Your own computer. This is the default when a usable keychain exists. |
file | A private file in your user configuration directory: ~/.config/signatureapi/credentials (or under $XDG_CONFIG_HOME), or %APPDATA%\signatureapi\credentials on Windows. | Containers, CI, and headless Linux, where no keychain is available. |
Without --credential-store, the CLI uses the keychain when it can, and falls back to the file store when it can’t. To choose one, pass it on every command:
npx signatureapi login --credential-store file
npx signatureapi init --credential-store file
The file store lives outside your project, so it never ends up in your repository. To keep a sign-in across container restarts, keep that directory on a persistent volume.
whoami
npx signatureapi whoami
Shows the account the stored sign-in acts for, as its acc_ ID. It is the same ID the MCP server’s whoami tool returns, so you can check that the CLI and an agent act for the same account.
whoami never starts a sign-in. Without one, it fails with authorization-required.
To read the account ID from a script:
npx signatureapi whoami --json
{"type":"result","status":"success","code":"signed_in","next_actions":[],"account":{"id":"acc_..."}}
logout
npx signatureapi logout
Revokes the CLI’s sign-in and deletes it from this machine. Without --credential-store, it signs out of both the keychain and the file store. To sign out of one store only:
npx signatureapi logout --credential-store file
logout removes the local sign-in even when it cannot confirm the revocation; it then reports logout_revocation_unconfirmed. With no sign-in anywhere, it reports not_logged_in.
API keys, webhook endpoints, and env files stay as they are. Revoke an API key separately with api-keys revoke.
Switch account or organization
The CLI keeps one sign-in per store. To act for another organization, sign out and sign in again:
npx signatureapi logout
npx signatureapi login
Permissions
What the CLI can do follows your role in the organization:
- API key commands need permission to manage API keys, plus access to the mode of the key.
listenandtriggerneed permission to manage webhooks, plus test-mode access.
Live mode also needs an active account. Without live-mode access, live commands fail with live-mode-unavailable.