Overview

subak is the command-line interface for the Subak framework. It validates artifacts against the embedded workflow DAG, installs git hooks, registers the MCP server your agent uses, and drives the rest of the authoring loop. This section is a complete reference for every public command, grouped by what you're trying to do.

If you're new, start with Getting Started — it walks you through install, authentication, and your first project. This page is the reference: install, versioning, the command tree, flag conventions, and the environment variables the CLI reads.

Install

Install the binary with the one-line script. It detects your platform, downloads the matching release, verifies its checksum, and puts subak on your PATH:

curl -sSfL https://subak.ai/install.sh | sh

The CLI ships native builds for macOS, Linux, and Windows. To upgrade an existing install later, use subak update (it pulls from the same release channel the install script uses).

Check the version

subak version

Print the CLI version, commit, and build date.

subak version [flags]

The text output looks like subak v0.1.0 (a1b2c3d, built 2026-06-07).

Flag	Type	Default	Description
--json	bool	false	Emit structured JSON ({version, commit, builtAt}).

caution

subak --version does not work — the root command does not wire a --version/-v flag, so passing it errors as an unknown flag. Always use the subak version subcommand. This matters because the build workflow installs the binary via go install; subak version is how you confirm which build is actually on your PATH.

When to use: To confirm which build is on your PATH.

subak version
subak version --json

For help on any command, use standard cobra help: subak help, subak <cmd> --help, or -h.

Command tree

subak
├── validate [rule-name]     run structural / validation / semantic checks (proof-tree v2 default)
├── verify <hash>            verify a proof certificate by hash
├── inspect                  interactive TUI to explore a proof tree
├── status                   print repo state + last validate result
│
├── init                     initialize a Subak project (onboarding orchestrator)
├── login                    authenticate against the service; store an API key
├── logout                   remove the stored API key
├── pull                     download remote artifact blobs into the local cache
├── push                     upload local artifact blobs to the service
├── project                  manage the local project registry
│   ├── register             register/update a (workspace, project) → path mapping
│   ├── unregister           remove a (workspace, project) entry        [rm, remove]
│   ├── list                 list registry entries                      [ls]
│   └── path                 print the absolute path for an entry
├── artifact                 CLI fallback for the MCP artifact tools (persistent: --workflow)
│   ├── get                  fetch an artifact
│   ├── put                  write an artifact
│   ├── rehash               sync subak.json from the on-disk tree
│   └── ping                 verify the MCP server starts and responds
├── workflow                 manage the project's workflow pin
│   └── types [<workflow>]   print subak types as type:pattern lines
├── schema [name]            print the embedded JSON Schema for an artifact type
│
├── mcp                      manage the local MCP server + agent-client registration
│   ├── serve                run the MCP server over stdio
│   ├── install              register Subak MCP in detected agent clients
│   └── uninstall            remove the Subak MCP entry from agent clients
├── hook                     install git hooks that run subak validate
├── unhook                   remove subak-managed git hooks
├── skill
│   └── install              install Subak agent skill bundles into .claude/skills/
├── report
│   └── html <report.json>   render a validation JSON report as HTML
├── version                  print CLI version / commit / build date
├── update                   self-update the CLI to the latest release
├── generate                 generate code/test artifacts (advanced)
│   ├── code                 generate code skeletons
│   ├── relatedcode          record emitted code-file paths onto relatedCode[]
│   ├── enrich-tests         enrich scaffold test artifacts via the model
│   └── tests                generate test-file skeletons {api, unit, proptest, contract}
└── migrate                  one-shot codemods that rewrite artifacts in bulk
    └── page-to-slice        convert legacy page artifacts to slice[layer=page]

The pages in this section cover these groups:

• Validation & Inspection — validate, verify, inspect, status.
• Projects & Artifacts — init, login/logout, project, artifact, pull, push, workflow types, schema.
• Integrations & Automation — mcp, hook/unhook, skill install, report html, update, and the advanced generate and migrate families.

Flag conventions

The root subak command registers no persistent (global) flags of its own — running bare subak just prints help. Every flag documented in this section is local to its command. There is no shared --workflow, --json, or --verbose that applies everywhere; each command re-declares the flags it needs, with its own defaults (for example --workflow defaults to software, booleans default to false).

Two command groups are the exception: they use group-level persistent flags inherited by their subcommands.

• The artifact group has a persistent --workflow flag (default software) shared by get, put, rehash, and ping.
• The generate tests group shares --workflow, --dry-run, --bc, and --type with its api/unit/proptest/contract subcommands.

Common conventions you'll see across many commands:

• --json — emit structured JSON instead of human-readable text (good for scripting / CI).
• --dry-run — show what would happen without writing anything (pull, push, artifact rehash, generate *, migrate *).
• --workspace / --project — override the workspace/project slugs that otherwise default from the nearest subak.json (walk-up from the current directory).
• --workflow — the workflow a command operates against; almost always defaults to software.

Exit codes

Most commands return 0 on success and 1 on failure. The proof-certificate commands use a finer mapping: 0 success, 1 generic error or a tampered certificate, 2 certificate not found. subak validate exits 1 directly on validation failure, which is what makes it usable as a git-hook gate.

Environment variables

The CLI reads the following SUBAK_* (and a few related) environment variables. None are required for normal use — they're escape hatches for CI, on-prem, and advanced setups. Credentials themselves are stored in your OS keychain by default (or ~/.subak/credentials.json when --file is used), not in an environment variable.

Variable	Read by	Meaning
SUBAK_STORE_MODE	pull, push, validate, artifact *, mcp serve, migrate	Forces the artifact-store mode: customer, local, or dogfood. Overrides auto-detection (credentials present → customer, else → local). dogfood is never auto-detected; you must set it explicitly.
SUBAK_SERVICE_URL	login, init	Overrides the service base URL (default https://api.subak.ai). A --service flag, where present, takes precedence over this.
SUBAK_PROOF_SIGNING_KEY	validate, verify	HMAC key used to sign and verify the proof certificate. When set, a signature mismatch is fatal (tampered). When unset, signing/verification is skipped.
SUBAK_PROOF_BUCKET	validate	When set (with AWS credentials available), proofs are written through to this S3 bucket in addition to the local .subak/certs/ store.
SUBAK_PROOF_PREFIX	validate	S3 key prefix for the proof bucket above.
SUBAK_BEHAVIORAL	validate (--v1 path)	=1 opts in the behavioral test collector (runs go test). Off by default.
SUBAK_SWIPLBIN	validate	Override the path to the swipl (SWI-Prolog) binary. If unset, looked up on PATH; absence falls back to the gofunc engine.
SUBAK_CLIPPY_PLUGIN_BIN	validate	Override the clippy-plugin-subak binary used by the Rust static-code checker. Empty → PATH lookup.
SUBAK_ESLINT_PLUGIN_BIN	validate	Override the eslint-plugin-subak binary used for JS/TS static checks.
SUBAK_REVIEWER_DISABLED	validate	=1 disables the Tier-3 LLM reviewer wiring entirely (a no-op reviewer stays).
SUBAK_REVIEWER_API_KEY	validate	API key for explicit reviewer opt-in (CI / on-prem), used when the local claude CLI is absent.
SUBAK_REVIEWER_MODEL	validate	Model for the API-key reviewer path (default claude-haiku-4-5).
SUBAK_REVIEWER_MAX_TOKENS	validate	Max tokens for the reviewer path (default 512).
SUBAK_REVIEWER_TIMEOUT	validate	Reviewer request timeout (default 30s).
SUBAK_REVIEWER_BASE_URL	validate	Optional base URL for on-prem reviewer proxies / tests.
ANTHROPIC_API_KEY	validate, generate enrich-tests	Enables the Claude LLM reviewer / enrichment. When unset, the no-op reviewer is used and semantic rules report deferred.
GEMINI_API_KEY	validate	Enables visual interface verification of demos — a vision-capable LLM checks that your running app's interface looks the way it should; the check is skipped when unset.
SUBAK_BASE_URL	update	Override the release-channel base URL for self-update (falls back to --base-url, then the built-in default).

note

When SUBAK_PROOF_BUCKET is set, the standard AWS SDK config is also consulted, so AWS_PROFILE / AWS_REGION / other AWS_* variables apply transitively.

Experimental / hidden commands

The CLI ships a handful of pre-alpha, internal commands that work but are intentionally omitted from subak --help and are not part of the stable CLI surface: scaffold, trace, render, loop, emit, and workflow update. Their flags and behavior may change or be removed without notice, so they are not documented as stable API here. If you discover one, treat it as unstable and unsupported. A short recap lives at the end of Integrations & Automation.