sign-cli: Instructions file for Codex

Agents

Drive sign-cli from an LLM or non-interactive client. This is the quickstart; the full canonical reference is docs/agent-guide.md.

Output contract

• Success: JSON to stdout, exit 0.
• Failure: { ok: false, error: { code, message, hint?, details? } } to stderr, non-zero exit.
• Toggle to plain text: SIGN_ERROR_FORMAT=text.

Exit codes

Code	Meaning
0	Success
2	Invalid input (missing/malformed flag, schema fail)
3	Policy / chain / verification failed
4	Not found / out of range

Full code table and the failure-mode → recovery map: docs/reference/exit-codes.md.

Discovery

Never hardcode tool names, flag lists, or counts — call these at startup:

sign --catalog json    # full CLI command + flag inventory
sign mcp tools         # live MCP tool catalog (with inputSchema/outputSchema)
sign --version

The signing asymmetry

The whole architecture is built around one rule: the agent does every step except the signing gesture. sign (CLI / MCP tool / POST /v1/sign) requires a per-signer token that's scoped to one email, TTL-bounded, single-use. The requester (which can be the agent) holds and DMs the token to the human signer; the signer pastes it into sign sign --token .... The agent never sees signer tokens.

Pre-sign safety checks (--require-hash, --require-title, --require-signer-email) throw structured errors before any state mutation, so an agent computing a hash earlier can refuse to sign if the document was swapped in flight.

Read-only mode

For sandboxed agents that should inspect and track but not mutate:

sign mcp serve --read-only true \
  --tool request_show --tool audit_verify --tool pdf_detect_signature_field
sign serve --read-only true --rate-limit 5

Mutating tools/routes return FORBIDDEN_READ_ONLY (exit 3 / HTTP 403). The set is in READ_ONLY_BLOCKED_TOOLS and READ_ONLY_BLOCKED_ROUTES in the source.