Commands
API keys
Write a SignatureAPI API key into your env file, and list, create, roll, and revoke API keys from the CLI.
The CLI puts API keys where your application reads them: a variable in your env file. It never prints a key, so keys stay out of your terminal history, logs, and agent transcripts.
init
npx signatureapi init
Writes the account’s API key into the env file, signing in first when needed. Run it from your application’s directory.
- Test mode (the default) copies the account’s existing test key. It never creates or rolls a test key.
- Live mode (
--mode live) creates a new live key, unless the variable already holds a live key. An existing live key is kept as it is, and the result iscredentials_retained.
By default, the key goes into SIGNATUREAPI_KEY in .env, or in .env.local when the project’s package.json depends on next.
| Option | Description |
|---|---|
--mode <mode> | Which key to write: test (the existing test key) or live (a new live key). Default: test. |
--env-path <path> | Env file to write to, inside the current directory. Created when missing. Default: .env, or .env.local in Next.js projects. |
--var <name> | Env variable that holds the API key. Default: SIGNATUREAPI_KEY. |
--replace | Overwrite the variable when it already holds a different key. |
--description <text> | Label for a new live key, shown in the Dashboard and in api-keys list. Up to 255 characters. |
--skills | Also install the SignatureAPI agent skills. See Agent setup. |
--mcp | Also register the SignatureAPI MCP server. |
--agent <name> | Agent to configure with --skills and --mcp. Repeatable. |
--global | Configure agents for your user instead of this project. |
--yes | Apply agent setup without the prompt. It never confirms a key change. |
--no-agent-setup | Don’t offer to set up detected coding agents after saving the key. |
Every command also takes --credential-store and --json. See Sign in and Output and exit codes.
Examples:
# Write the test API key into .env (.env.local in Next.js projects)
npx signatureapi init
# Write it into another file and variable
npx signatureapi init --env-path .env.development --var MY_SIGNATUREAPI_KEY
# Create a labeled live key in .env.live
npx signatureapi init --mode live --env-path .env.live --description "Billing worker"
# Save the key without the coding-agent offer
npx signatureapi init --no-agent-setup
In a terminal, once the key is saved, init offers to set up the coding agents it finds on your machine that don’t have SignatureAPI yet. See Agent setup.
Test and live keys
An account has one test key and up to four live keys: five active keys in total.
- Test key. Created with the account.
initretrieves it, andapi-keys roll --mode testchanges its value. It cannot be created or revoked. - Live keys. Created by
init --mode liveorapi-keys create. Live mode needs an active account and an organization role with live-mode access.
Keep test and live keys apart. The CLI refuses to write a key into a variable that holds a key of the other mode (mode-mismatch). Use another --var or --env-path for each mode, for example .env for test and .env.live for live.
Changes to live keys ask for confirmation first. In a non-interactive shell, pass --yes; without it, the command fails with confirmation-required before it signs in or changes anything. Declining the prompt changes nothing and reports confirmation-declined.
Lost live-key values cannot be retrieved. To replace one, roll the key or create a new one.
api-keys list
npx signatureapi api-keys list
Lists the account’s API keys: ID, mode, description, and last four characters. The key itself is never shown.
| Option | Description |
|---|---|
--mode <mode> | Only list the keys of this mode: test or live. Both modes when omitted. |
# List every key
npx signatureapi api-keys list
# List live keys as JSON
npx signatureapi api-keys list --mode live --json
Without --mode, a sign-in without live-mode access lists its test keys, and the next step says live keys were not listed. When one mode fails for another reason, the CLI still shows the other mode’s keys and reports keys_listed_partial.
api-keys create
npx signatureapi api-keys create --env-path .env.live --description "Billing worker"
Creates a live API key and writes it into the env file. To get the test key, use init.
| Option | Description |
|---|---|
--env-path <path> | Env file to write to, inside the current directory. Created when missing. |
--var <name> | Env variable that holds the API key. Default: SIGNATUREAPI_KEY. |
--replace | Overwrite the variable when it already holds a different key. |
--description <text> | Label for the new key, shown in the Dashboard and in api-keys list. |
When the account already has five active keys, the command fails with cli-key-limit-reached. Revoke a live key you no longer use, or roll an existing key instead.
api-keys roll
npx signatureapi api-keys roll key_... --mode test --replace
Replaces an API key’s value and writes the new value into the env file. The old value stops working at once. Rolling does not change the number of active keys.
| Argument or option | Description |
|---|---|
<api-key-id> | ID of the key (key_...), as api-keys list shows it. |
--mode <mode> | Mode of the key to roll: test or live. Required. |
--env-path <path> | Env file to write to, inside the current directory. Created when missing. |
--var <name> | Env variable that holds the API key. Default: SIGNATUREAPI_KEY. |
--replace | Overwrite the variable when it already holds a different key. |
--yes | Confirm a live key change without the prompt. Required in non-interactive shells. |
The variable usually holds the old value, so a roll needs --replace. When the variable already holds any value, create and roll without --replace fail with credential-conflict before they change a key.
# Roll the test key
npx signatureapi api-keys roll key_... --mode test --replace
# Roll a live key in a non-interactive shell
npx signatureapi api-keys roll key_... --mode live --env-path .env.live --replace --yes
api-keys revoke
npx signatureapi api-keys revoke key_...
Revokes a live API key so it stops working. It asks for confirmation. The test key cannot be revoked.
| Argument or option | Description |
|---|---|
<api-key-id> | ID of the key (key_...), as api-keys list shows it. |
--yes | Confirm without the prompt. Required in non-interactive shells. |
# Revoke a live key without the prompt
npx signatureapi api-keys revoke key_... --yes
How the CLI writes env files
Every command that writes a key or secret follows the same rules:
- Inside the current directory.
--env-pathmust name a file inside the directory the command runs from. Run commands from your application’s directory. - Private. A new env file is created readable and writable by you only. When an existing env file is readable by other users or writable by its group, the CLI removes those permissions; group read stays, so a file shared with a group keeps working.
- Out of Git. In a Git repository, the CLI refuses an env file that Git tracks. When the file is not ignored yet, the CLI adds it to
.gitignore. - Everything else untouched. Other variables, comments, and line endings stay as they are.
- No silent overwrites. When the variable already holds a different key, the command fails with
credential-conflict. Pass--replaceonly when you mean to replace it.--yesnever replaces a value.
If a key was created or rolled but could not be written to the env file, the result names the key ID and how to recover. When the CLI cannot confirm that a creation or roll happened, it reports key_creation_unconfirmed or key_roll_unconfirmed and does not retry. Check api-keys list before you try again.
Keys in the Dashboard
Keys you create or roll with the CLI are the same keys you see on the Dashboard’s API keys page. See Authentication for how your application sends a key with each request.