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 is credentials_retained.

By default, the key goes into SIGNATUREAPI_KEY in .env, or in .env.local when the project’s package.json depends on next.

OptionDescription
--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.
--replaceOverwrite 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.
--skillsAlso install the SignatureAPI agent skills. See Agent setup.
--mcpAlso register the SignatureAPI MCP server.
--agent <name>Agent to configure with --skills and --mcp. Repeatable.
--globalConfigure agents for your user instead of this project.
--yesApply agent setup without the prompt. It never confirms a key change.
--no-agent-setupDon’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. init retrieves it, and api-keys roll --mode test changes its value. It cannot be created or revoked.
  • Live keys. Created by init --mode live or api-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.

OptionDescription
--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.

OptionDescription
--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.
--replaceOverwrite 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 optionDescription
<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.
--replaceOverwrite the variable when it already holds a different key.
--yesConfirm 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 optionDescription
<api-key-id>ID of the key (key_...), as api-keys list shows it.
--yesConfirm 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-path must 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 --replace only when you mean to replace it. --yes never 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.