CLI Reference
The signstack CLI treats agreements as source: you author resources as YAML on disk, validate them, preview what they render to, push them to your namespace, and start workflows from them.
# macOS and Linux
curl -fsSL https://cdn.signstack.ai/cli/install.sh | sh
# Windows (PowerShell)
irm https://cdn.signstack.ai/cli/install.ps1 | iex
It needs Node.js 20.17 or newer, and keeps itself up to date — a patch release installs quietly in the background, and a larger one is applied before your next command. signstack <command> --help lists any command's flags.
Conventions
- Name the resource.
signstack validate my_nda@draft -d .acts on exactly that resource. Omit it and the CLI opens an interactive picker instead. - The project folder flag differs by command:
-d <dir>forvalidateandpush,-p <dir>forpreviewandrun. Both default to the current directory and search it recursively. - The target is fixed at login. The API endpoint, organization and namespace all come from your stored login; no command overrides them. To switch, log in again.
--jsoneverywhere. Every command accepts it, and in that mode it never prompts.
Machine-readable output
Pass --json and standard output carries exactly one JSON document — progress and spinners go to standard error, so merging the two still leaves a parseable document.
{ "ok": true, "…": "the command's payload" }
{ "ok": false, "error": { "message": "…", "suggestions": ["…"], "statusCode": 403 } }
suggestions and statusCode appear when they are known. Any failure also exits non-zero, so a pipeline can gate on the exit code alone. validate, push and pull are the exception to the error shape: when they fail after producing per-resource results, they return those results with ok: false.
Authentication
signstack auth login # prompts for an API key
signstack auth whoami # reports the stored login
signstack auth logout
validate, preview, push, pull and run all need a login.
-
Keys are scoped, and scopes cannot be added later. Authoring from files needs
resource:read,resource:createandresource:update; starting workflows needs theworkflowscopes as well. A403names the scope that was missing — the fix is a new key. See Scopes. -
Test keys (
sk_ns_test_…) only reach test data; live keys (sk_ns_live_…) reach production. -
whoamiis offline. It reads local state, so a revoked key still reports as authenticated until a command contacts the server."tokenExpired": trueis harmless — the next command refreshes the token. -
In CI, pipe the key in rather than passing it as an argument:
echo "$SIGNSTACK_API_KEY" | signstack auth login --api-key-stdin
validate
signstack validate <key>@<version> -d <dir> --json
Checks the named resource and everything it references, leaf first: each document against its kind's schema, then the cross-resource rules — references resolve, no dependency cycles, step keys unique, every template input supplied, schema definitions valid JSON Schema.
| Flag | Effect |
|---|---|
--no-remote |
A dependency missing from disk is an error, instead of being looked up in your namespace. |
--no-deps |
Check only the named resource against its own schema; skip dependencies and cross-resource rules. |
--kind <kind> |
Disambiguates when two kinds share a key@version: blueprint, template, schema, asset, jsonata-function. Giving every resource its own key avoids needing it. |
--verbose |
Adds dependency-graph statistics. |
A dependency that is absent from disk but published in your namespace passes, unless you pass --no-remote — so a project can build on resources that are already there.
What validate does not check
It checks structure, and that keys, references and inputs line up. It does not run your data.transform, check a scenario against the input schemas, compare the transform's output with an HTML asset's data.schema, or compile the Handlebars.
A wrong data path, a missing [], a misspelled {{variable}}, an unknown helper or a value printed in the wrong place all pass validation. They surface in preview — an unknown helper also fails when push saves the asset. A passing validate is necessary, not sufficient: read the previewed PDF before you ship a document.
Common validation errors
| Message | Cause | Fix |
|---|---|---|
Version is required |
A folder path was given where key@version belongs. |
signstack validate <key>@<version> -d <folder> |
Multiple resources found for <key>@<version> |
Two resources of different kinds share one key. | Give each its own key (lease, lease_template, lease_html), or pass --kind. |
Referenced <Kind> '<key>@<version>' not found |
The reference's version does not match the target's metadata.version, the key is misspelled, or the file is outside -d. |
Make the reference match exactly. New work is draft everywhere. |
must match pattern "^[a-z][a-z0-9]*(_[a-z0-9]+)*$" |
A key is not snake_case. | Rename it, and every reference to it. |
must NOT have additional properties |
A field that does not exist at that level. | Remove or rename it. |
must have required property 'execution' |
A group step without execution. |
Add execution: sequential or parallel. |
must have required property 'schema' under output |
A role output with only a transform. | Add schema: — both are required. |
must be boolean on required |
required: "$.something" written as a bare string. |
Use required: { expression: "..." }, or true / false. |
Required template input "x" is not provided |
No blueprint input of that key, and no inputMap entry. |
Rename to match, or add inputMap: { x: "$.<blueprintInput>" } — an inputMap must then list every input of that document. |
Versioned resources cannot depend on draft resources |
A published version references a @draft resource. |
Publish the set together, or keep it all on draft. |
resolves outside the project directory |
A file: path climbs out of the folder you pointed at. |
Move the file inside the project, or point -d at the real root. |
| YAML will not parse | An unquoted value containing : , or starting with #, &, *, ` |
, >, %, @` or a backtick. |
More symptoms, including rendering problems, are in Troubleshooting & FAQ.
preview
signstack preview <blueprint>@<version> -p <dir> --scenario <name> --json
signstack preview --template <template>@<version> -p <dir> --scenario <name> --json
signstack preview -p <dir> --list-scenarios
Renders the documents with a scenario's data and returns short-lived PDF links — one per document, under envelopes[].documents[].signedUrl, each valid for an hour.
- Pass
--scenario. Without it, preview takes the alphabetically first file inscenarios/. With no scenario files at all, it asks SignStack's AI to invent data and writes new files intoscenarios/; the response then reportsentityData.source: "generated"and lists what it wrote. --resolvechooses where resources come from:auto(default) takes the named resource and anything else found on disk from your files and the rest from your namespace;localrequires everything on disk;remoteignores your files.- Signature, initial and date fields are filled with sample marks.
--skip-signature-fieldsleaves them empty. - Preview uploads your files for rendering but creates no resource — nothing has to be pushed first.
push
signstack push <key>@<version> -d <dir> --dry-run --json # validate and show the plan; writes nothing
signstack push <key>@<version> -d <dir> --json
Validates, then creates the resource and its dependencies in your namespace, leaf first, uploading any file: contents.
| What is already stored | Outcome |
|---|---|
| nothing | created |
| an identical resource | already exists, skipped |
a draft that differs |
draft updated — overwritten in place. There is no merge: edits made in the Studio since your last push are lost |
| a published version that differs | conflict — published versions never change; bump the version |
If someone may have edited the draft in the Studio, pull it first and compare. Scenario files stay local: neither push nor pull carries them.
pull
signstack pull <key>[@<version>] --kind blueprint -o <parent-dir> --json
Downloads a resource and all its dependencies into a new folder under -o. It never overwrites — a numeric suffix is added if the name is taken. --kind is required. Without a version it takes the latest published version, skipping drafts; ask for @draft explicitly to get one.
run
signstack run <blueprint>@<version> -p <dir> --scenario <name> --json
Creates a workflow in your namespace from the local files and the scenario's data, and starts it — participants receive signing emails immediately. Check which namespace you are pointed at (signstack auth whoami) and which addresses the scenario produces before running it for the first time.
--mode reviewcreates the workflow in review mode, and the link it prints opens the review page rather than the monitor.--timezone <Region/City>sets the timezone used for dates on this workflow's documents.--resolveworks as it does forpreview.
generate
signstack generate "a mutual NDA between two companies" -o <parent-dir>
signstack generate # interactive: browse the public Library
With a description, SignStack's AI writes a blueprint project into a new folder — this needs the ai-chat:use scope. Without one, it opens an interactive browser for the public Library, which needs no login.
If your key lacks the scope, the command explains how to generate with your own AI assistant instead — see Generating Contracts with AI.
In a pipeline
echo "$SIGNSTACK_API_KEY" | signstack auth login --api-key-stdin
signstack validate my_blueprint@1.0.0 -d ./signstack --json
signstack push my_blueprint@1.0.0 -d ./signstack --dry-run --json
signstack push my_blueprint@1.0.0 -d ./signstack --json
Add --api-url <url> to the login only for a non-default endpoint, and gate each step on its exit code. A fuller example is in CI/CD for primitives.
