API Docs

AI Toolkit

Pricing

$0.25

API Docs

AI Toolkit

Changelog

Pricing

$0.25

All posts
Devs

Our CLI is becoming a second dashboard

The SignatureAPI CLI now works with envelopes, recipients, events, deliverables, uploads and emails for coding agents and CI, and this post explains the credential, secrets and upload designs behind it.

There is a debate among developers right now about dashboards. One side of it holds that if a product needs a dashboard, the developers building on it would rather not use it, and that the ones who have to will soon ask a coding agent to rebuild whatever they need from the API. We think that side is right about where things are going, and we are building SignatureAPI as an agent-first platform. An agent should be able to do everything a person does in our dashboard without opening a browser, through the API, the MCP server or the command line.

The command line is where we expect agents to do most of that work. The CLI is the signatureapi package on npm, run with npx on Node 22.20 or later. Its main users are coding agents working inside a developer’s repository, and CI pipelines come second. Neither should have to click through a sign-in page or copy a key out of a settings screen, so every flow in the CLI has to work for a process that has no browser.

This week three releases moved the CLI toward that goal. Resource commands and API keys in CI shipped on November 16, one secrets rule shared by every entry point to an account on November 18, and uploads and emails on November 19 in version 0.7.0. The CLI has had nine stable releases since September 24 and now has 31 commands. This post explains how those commands work, which designs we rejected on the way, and why.

Keeping agents away from secrets

The cautious way to handle API keys and webhook signing secrets in a CLI is to keep agents away from them. The CLI could try to detect that an agent is running it and refuse to show a secret, or it could ask for a confirmation that only a person can give before ordinary operations. Both versions are simple to state, and both look safe.

Followed through, they work against the users we are building for. If agents are the main users of the CLI, a rule that refuses to serve agents, or stops them to wait for a person during routine work, degrades the CLI exactly where it gets the most use. It also protects the wrong thing. A secret becomes a problem when its value lands somewhere it shouldn’t, such as a terminal transcript or a log, and that happens the same way whether a person or an agent typed the command. We made a secret’s protection depend on where its value goes, and left the question of who is running the command out of it.

Passing the API key as a flag

CI has to authenticate without a sign-in, and the conventional answer is an --api-key flag that takes the key’s value. It keeps a command self-contained on one line, which is exactly why it is tempting to put in a pipeline definition or paste into an agent’s instructions.

The trouble is everywhere that line goes after it runs. A value passed as an argument ends up in shell history, in process lists and in logs. The CLI reads a key only from an environment variable. That is SIGNATUREAPI_KEY by default, or a variable you name with --api-key-var. No option accepts a key value.

Rewriting envelope bodies to upload local files

Creating an envelope needs documents, and when someone works from a terminal the document is usually a file on disk. The convenient design is for the CLI to accept a local path inside the envelope body, upload the file, and swap the path for the uploaded URL before it sends the request. For a single command typed by hand, that is hard to beat.

The cost is that the CLI would accept envelope bodies the API rejects. An agent that learned the body format from the CLI would then write bodies that fail as soon as it calls the API or the MCP server directly, and every difference of that kind has to be documented and kept in step from then on. We kept the body the CLI sends identical to the body the API accepts. Uploading is a command of its own, uploads create, which returns something the envelope body can reference, and its --key option makes that upload permanent.

A separate copy of each operation per entry point

An account has four entry points: the public API, the dashboard, the MCP server and the CLI. The quickest way to give the CLI a new operation would have been to write it again for the CLI, with its own checks and its own version of the rules about secrets. Each entry point could then change at its own pace without waiting on the others.

That freedom turns into a liability the first time a rule changes. A change to which secrets may be shown would need four separate edits, and whichever entry point missed one would become the easiest way around the rule. Instead, every entry point resolves the caller to the same account identity and calls one shared set of operations with one secrets rule. A rule written once applies to all four in the same change, which is how the secrets rule described below reached the API, the dashboard, the MCP server and the CLI on the same day.

What we shipped

The CLI now has resource commands that work signed in or with a key, a secrets rule that decides where each secret may go, confirmations on the commands that change things, uploads that can be kept under a key, and help and errors written for a caller that acts on them without a person in the loop.

Resource commands

Fifteen of the 31 commands work with account resources.

ResourceCommands
Envelopeslist, get, create, cancel, delete
Recipientsresend, replace, ceremony
Eventslist
Deliverableslist, get
Uploadscreate, inspect
Emailslist, get

The rest cover the account itself (login, init, whoami and logout), local webhook development (run, listen and trigger), API keys, webhook secrets, and agent setup, which installs our agent skills and MCP server for 11 coding agents.

Every resource command takes --json, and all of them except the uploads commands take --mode test|live. With --json the output is NDJSON. Progress events come first, one per line, and the command ends with a single result line that carries the credential it used, the mode, the data, a next_cursor for paging and a problem when something went wrong. The exit code is 0 for success, 1 for a failure or a partial result, and 2 for a usage error, so a script can branch on the code and read the result line only when it needs the details.

Test data only. Creating an envelope in test mode with --json, taking its ID with jq, and listing its events.

Partial results matter most for commands that change something. When the outcome of a change is unknown, the result is a partial *_unconfirmed result and the CLI never sends the request again on its own. Resending a create whose outcome is unknown could leave the account with two envelopes, so the CLI reports what it knows and leaves the next step to the caller.

Signing in or using a key

Signing in shows a device verification URL and a user code, which a person opens and confirms in their own browser. When the CLI runs without an interactive terminal it never tries to open a browser itself. The credentials it receives are stored in the operating system keychain, with a file as the fallback.

Each command picks its credential in a fixed order. A variable named with --api-key-var comes first, then SIGNATUREAPI_KEY, then the sign-in. With a key, the key’s own mode decides whether the command runs in test or live mode, and a --mode that conflicts with the key fails with api-key-mode-mismatch before any request is sent. Signed in, the default mode is test. The emails commands require the sign-in and fail with sign-in-required when given a key. An organization admin can also turn CLI access off in the dashboard, after which commands for that organization fail with cli-access-disabled.

Where secrets go

The secrets rule shipped on November 18 and is the same on the public API, the dashboard, the MCP server and the CLI. It puts every secret in one of three classes.

ClassSecrets
ReadableTest API keys, test webhook secrets
Reveal-guarded and auditedLive webhook secrets
Show-onceLive API keys

In the CLI, a command that produces a secret sends it to one of three destinations. The default is your env file. With --pipe -- <cmd> the value goes to another command, and it appears in the terminal only when you pass --show-secret. Every result names where the secret went, so the caller knows where to find it. The key value never appears in output, error messages or next-action hints, which name the environment variable instead. Some requests are refused outright. api-keys reveal --mode live fails with not-revealable, since a live key is shown once, and test keys can’t be revoked.

For local development, run starts your own command with the test key, and the local listener’s secret, in its environment.

Terminal
npx signatureapi run -- npm test

The key is never written to disk, and any occurrence of it in the child’s output is replaced with <concealed by signatureapi>. Masking is not isolation, and the docs say so. The child process still receives the key, so the mask keeps the value out of what gets printed and does nothing beyond that. run --mode live fails with invalid-options.

Test data only. A secret written to an env file, then run starting a command whose output shows the key as <concealed by signatureapi>.

Confirmations

envelopes cancel and envelopes delete always ask for confirmation. In live mode, envelopes create and the three recipients commands ask as well. When there is no interactive terminal and no --yes, these commands fail with confirmation-required and exit with code 2, the code for a usage error. Any caller can pass --yes, an agent included, so the confirmation asks for an explicit decision without asking for a person.

We kept --json separate from consent. A caller that asks for machine-readable output has said how it wants the answer, not that it agrees to cancel an envelope, so --json does not skip the prompt.

Uploads with a key

uploads create <path> accepts a PDF, DOCX or PNG file. Before sending the file, the CLI gets a single-use upload URL, so a file over the account’s maximum document size is refused before any byte leaves the machine. The result carries a url, which is the value for a document’s url in envelopes create. An upload expires after 24 hours unless you give it a key with --key, which stores it permanently. A key is 1 to 100 lowercase letters, digits, hyphens and underscores, unique within the account.

Terminal
npx signatureapi uploads create template.pdf --key contract-template-v2

Uploads work with both the sign-in and an API key, and the account’s maximum document size is the only limit on them. A template used in every envelope can be uploaded once under a key and its url reused from then on, instead of being uploaded again for each envelope.

Test data only. uploads create with --key, then an envelope that uses the stored upload.

Help and errors for a caller that acts on them

The help for every command includes examples, the global options and a link to its docs page, and a test checks this for all 31 commands. A usage error carries a message and a next action that names the --help command to run. The message never repeats the rejected value.

init treats agents differently in one respect. When it runs under an agent, it installs nothing and prints the exact agent setup command to run instead.

Where this is going

We believe agents are here to stay. For many developers they are already how software gets built, not an experiment running beside it, so agents are the present of this work as much as its future. We expect more of every integration to be written, tested and run by an agent, with a person reviewing the result.

That is why we are building SignatureAPI agent first. Our aim is for every capability to reach the API, the MCP server and the CLI, under the same rules for secrets and confirmations that the dashboard follows. The CLI will keep growing in that direction, with output, errors and help written for a caller that reads them and acts on its own.

To try the CLI, start with the CLI overview.

START FOR FREE

Ready to get started?
Create an account instantly, no credit card required.

Get Started