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 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> --reason "wrong environment"
sapient approvals escalate <id>

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

Spec editing, ticket and product management, and billing actions live in the web app for now. sapient covers signup through daily operation; it isn’t yet a full replacement for the control room.