CLI

sapient runs your company from the terminal: sign up, create a factory, import an existing project, then keep working — onboarding, chat, approvals, status — without opening the web app.

Everything the CLI does, the web does too. Use whichever fits the moment: the wizard is nicer the first time, the CLI is better when you’re already in the repo.

Install

During the design-partner phase, binaries come from the release page (org access required):

gh release download -R Sapient-Works/sapient-cli \
  -p "*$(uname -s | tr A-Z a-z)_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/')*"

Or build from source (Go 1.26+):

go build -o sapient .

Check it:

sapient version

Log in

sapient login

This opens app.sapient.works/cli/auth in your browser. Sign in with any provider — Google, GitHub, or email — and click Authorize; the terminal shows a confirmation code so you can be sure the page you’re approving belongs to the session you started.

Security

Nothing secret travels through the browser. The CLI holds a one-time verifier and claims its credential directly from the API; the grant is single-use and expires in five minutes.

Other modes:

sapient login --email        # email/password, no browser
sapient signup               # create an account entirely from the terminal
sapient whoami               # who am I, and against which environment
sapient auth status          # exactly which credential source is active
sapient logout

Security

Your long-lived refresh token lives in the OS keyring (service works.sapient.cli). Everything else is short-lived state under ~/.config/sapient/, mode 0600.

Start a project

From inside a repository you already have:

cd ~/code/my-project
sapient init

init detects the repo, creates a factory, walks the same onboarding your first web session would — product name and mission, structure and surfaces, GitHub App install, repository selection, and the spec step — and imports your codebase so the spec is written from what’s actually there.

Every prompt has a flag, so it’s scriptable:

sapient init --yes --name "Acme Time" --repo acme/timetracker

Interrupted, or started on the web? Resume:

sapient onboard              # continue the current factory's wizard
sapient onboard <factory-id>

Work

sapient status               # where things stand: setup gaps, approvals, credits, tickets, digest
sapient chat                 # talk to your Chief of Staff
sapient chat @engineering    # DM a specific seat
sapient chat '#general'      # post to a team channel

Chat is where work starts. Ask your Product Manager for a product change — “add archiving to Taskly, so a task can leave the main list but stay searchable” — and it writes the change into your product spec as a draft and tells you where it landed. The draft waits in Approvals for you; it is not live until you approve it, and approving it bumps the product version.

chat is interactive by default. For scripts:

sapient chat --once "what shipped this week?"
sapient chat --tail                    # follow the conversation
sapient chat --json                    # NDJSON, one message per line

Approvals

Deploys, spending, outbound email, pricing, legal, hiring, and spec changes wait for a human.

sapient approvals list
sapient approvals approve <id>
sapient approvals reject <id> --comment "wrong environment"
sapient approvals escalate <id>

--comment works on both approve and reject: the note is recorded on the approval as its decision comment and shows up alongside the outcome in the control room. The one exception is a spec-change review — that decision is about the spec content itself, so the note is accepted but not recorded.

Approving one gate often unblocks the next. sapient approvals approve --all drains the chain to a fixpoint rather than making you re-run the command per link.

Factories

sapient factory list
sapient factory create --name "Acme Time"
sapient factory use <factory-id>     # set the default for this environment

The default factory is per environment, so a staging default never leaks into production commands.

CI and headless use

Export a token once, from a machine where you’re logged in:

sapient auth print-token --yes

Then in CI:

export SAPIENT_TOKEN=…
sapient status --json

With SAPIENT_TOKEN set, nothing is written to disk — no keyring, no config file.

Conventions

• --json on any read command gives machine output. NDJSON for chat.
• Data goes to stdout, errors to stderr, so sapient status --json | jq behaves.
• --env staging targets staging; the default is production.
• NO_COLOR, FORCE_COLOR, and CI are honored.
• Output is inline — never an alternate screen — so scrollback, pipes, and tee all work.

Exit codes

Code	Meaning
0	Success
1	API error
2	Usage error (bad flags or arguments)
3	Auth error — log in again

Branch on these in scripts rather than parsing messages.

Not in v1

There are no sapient commands for editing the spec, managing tickets and products, or billing — those live in the web app. (You can still get spec changes drafted from the terminal by asking your Product Manager in sapient chat; reviewing the diff and approving it happens in the control room.) sapient covers signup through daily operation; it isn’t yet a full replacement for the control room.