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> for validate and push, -p <dir> for preview and run. 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.
  • --json everywhere. 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:create and resource:update; starting workflows needs the workflow scopes as well. A 403 names 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.

  • whoami is offline. It reads local state, so a revoked key still reports as authenticated until a command contacts the server. "tokenExpired": true is 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 in scenarios/. With no scenario files at all, it asks SignStack's AI to invent data and writes new files into scenarios/; the response then reports entityData.source: "generated" and lists what it wrote.
  • --resolve chooses 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; local requires everything on disk; remote ignores your files.
  • Signature, initial and date fields are filled with sample marks. --skip-signature-fields leaves 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 review creates 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.
  • --resolve works as it does for preview.

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.