Smart Agent Teams

Command reference

Every sat command, argument and option, generated from the CLI itself.

This page is generated from the command definitions in apps/cli/src, so it always matches the CLI in this release. Run sat <command> --help for the same information in your terminal.

Global options

These work with every command.

OptionDescriptionDefault
-p, --profile <name>profile to use (local, staging, prod, or your own)
-c, --company <ref>company name, task prefix or id
--api-url <url>override the profile’s API URL
--jsonmachine-readable output (the API’s JSON)
-q, --quietonly print what was asked for
--no-colordisable colours (NO_COLOR is honoured too)

sat login

Sign in and store a session for the current profile

sat login [options]
OptionDescriptionDefault
--email <email>account email
--password-stdinread the password from stdin
--api-key-stdinstore an API key (read from stdin) instead of signing in

sat register

Create an account and sign in

sat register [options]
OptionDescriptionDefault
--email <email>account email
--name <name>your name
--password-stdinread the password from stdin

sat logout

End this profile’s session (--everywhere ends all of your sessions)

sat logout [options]
OptionDescriptionDefault
--everywherealso sign out every browser and CLI profile
-y, --yesskip the confirmation for --everywhere

sat whoami

Show who you are signed in as

sat whoami

sat apikey

Manage personal API keys (for runners and CI)

sat apikey create

Create an API key; it is shown once

sat apikey create <name> [options]
OptionDescriptionDefault
--expires-in-days <days>expire the key after this many days
--storealso store it as this profile’s credential

sat apikey list

List your active API keys

sat apikey list

sat apikey revoke

Revoke an API key

sat apikey revoke <name-or-id> [options]
OptionDescriptionDefault
-y, --yesskip confirmation

sat profile

Switch between local, staging, prod or your own API

sat profile list

List profiles

sat profile list

sat profile use

Make a profile the default

sat profile use <name>

sat profile set

Add or change a profile

sat profile set <name> [options]
OptionDescriptionDefault
--api-url <url>API base URL, e.g. http://localhost:8080
--events-url <url>origin for the live event stream, when the API URL buffers it

sat company

Companies you belong to

sat company list

List your companies

sat company list

sat company use

Set the default company for the current profile

sat company use <name-or-id>

sat company show

Show the current company

sat company show

sat company create

Create a company (you become its owner)

sat company create <name> [options]
OptionDescriptionDefault
--mission <text>what the company is for (- reads stdin)
--prefix <PREFIX>task key prefix, e.g. NF for NF-12SAT
--budget <dollars>monthly budget in dollars (0 = no limit)
--budget-cents <cents>monthly budget in cents
--usemake it the default company for this profile

sat company edit

Change the current company (owner/admin only)

sat company edit [options]
OptionDescriptionDefault
--name <name>
--mission <text>- reads stdin
--budget <dollars>
--budget-cents <cents>

sat company members

List the company’s members

sat company members

sat dashboard

What is happening, and does it need you (alias: status)

sat dashboard

sat inbox

Everything waiting on you: approvals, blocked tasks, failed runs

sat inbox [options]
OptionDescriptionDefault
--since <hours>failed runs from the last N hours24

sat costs

Spend by agent and project against budgets

sat costs [options]
OptionDescriptionDefault
--month <YYYY-MM>month to report (default: this month)

sat activity

The audit log: who changed what

sat activity [options]
OptionDescriptionDefault
--entity-type <type>task | agent | run | goal | project | approval | routine | company
--entity-id <id>
--before <iso>older than this time (for paging)
--limit <n>rows50

sat events

Stream live company events as JSON lines (pipe into jq)

sat events [options]
OptionDescriptionDefault
--types <list>only these types, globs allowed: task.*,run.updated

sat watch

A live dashboard that redraws as things change (Ctrl-C to quit)

sat watch

sat agents

Hire, manage and wake agents (alias: agent)

sat agents list

List agents with status and spend

sat agents list [options]
OptionDescriptionDefault
-a, --allinclude terminated agents
--status <status>only agents with this status

sat agents show

Show an agent, its open tasks and recent runs

sat agents show <agent>

sat agents hire

Hire an agent

sat agents hire <name> [options]
OptionDescriptionDefault
--request-approvalroute the hire through the approvals queue
--title <title>job title, e.g. "Senior Engineer"
--role <role>one of ceo, cto, cmo, cfo, engineer, designer, qa, devops, researcher, writer, support
--adapter <adapter>one of claude_code, codex, cursor, gemini, opencode, http
--reports-to <agent>manager (name or id; "none" for the top of the org)
--instructions <text>standing instructions (- reads stdin, @file reads a file)
--capability <list>capabilities, comma separated (repeatable)
--budget <dollars>monthly budget in dollars (0 = no limit)
--budget-cents <cents>monthly budget in cents
--heartbeat-cron <cron>wake on this schedule, e.g. "*/30 * * * *" ("none" to clear)

sat agents edit

Change an agent

sat agents edit <agent> [options]
OptionDescriptionDefault
--name <name>rename
--title <title>job title, e.g. "Senior Engineer"
--role <role>one of ceo, cto, cmo, cfo, engineer, designer, qa, devops, researcher, writer, support
--adapter <adapter>one of claude_code, codex, cursor, gemini, opencode, http
--reports-to <agent>manager (name or id; "none" for the top of the org)
--instructions <text>standing instructions (- reads stdin, @file reads a file)
--capability <list>capabilities, comma separated (repeatable)
--budget <dollars>monthly budget in dollars (0 = no limit)
--budget-cents <cents>monthly budget in cents
--heartbeat-cron <cron>wake on this schedule, e.g. "*/30 * * * *" ("none" to clear)

sat agents pause

Pause an agent: it stops being woken

sat agents pause <agent>

sat agents resume

Resume a paused agent

sat agents resume <agent>

sat agents terminate

Terminate an agent; its reports move to its manager and its open runs are cancelled

sat agents terminate <agent> [options]
OptionDescriptionDefault
-y, --yesskip confirmation

sat agents wake

Queue a run for an agent now

sat agents wake <agent> [options]
OptionDescriptionDefault
--task <ref>task to work on, e.g. NF-12
--reason <text>why it is being woken

sat org

Show the org chart

sat org

sat tasks

Work items: list, create, move, assign, comment (alias: task)

sat tasks list

List tasks

sat tasks list [options]
OptionDescriptionDefault
--status <list>filter by status (comma separated, repeatable)
--assignee <agent>filter by assignee
--project <project>filter by project
--goal <goal>filter by goal
--parent <task>subtasks of a task
-s, --search <text>search titles and descriptions
--mineonly tasks you created
--openhide done and cancelled tasks
--boardshow as columns by status
--limit <n>maximum rows200

sat tasks show

Show a task with its comments and runs

sat tasks show <task>

sat tasks create

Create a task

sat tasks create <title> [options]
OptionDescriptionDefault
--description <text>details (- reads stdin, @file reads a file)
--status <status>backlog | todo | in_progress | in_review | blocked | done | cancelled
--priority <priority>urgent | high | medium | low | none
--assignee <agent>agent name or id ("none" to unassign)
--project <project>project name or id ("none" to clear)
--goal <goal>goal title or id ("none" to clear)
--parent <task>parent task key or id ("none" to clear)
--due <date>due date, e.g. 2026-11-01 ("none" to clear)

sat tasks edit

Change a task

sat tasks edit <task> [options]
OptionDescriptionDefault
--title <title>
--description <text>details (- reads stdin, @file reads a file)
--status <status>backlog | todo | in_progress | in_review | blocked | done | cancelled
--priority <priority>urgent | high | medium | low | none
--assignee <agent>agent name or id ("none" to unassign)
--project <project>project name or id ("none" to clear)
--goal <goal>goal title or id ("none" to clear)
--parent <task>parent task key or id ("none" to clear)
--due <date>due date, e.g. 2026-11-01 ("none" to clear)

sat tasks move

Move a task to a status (backlog, todo, in_progress, in_review, blocked, done, cancelled)

sat tasks move <task> <status>

sat tasks assign

Assign a task to an agent ("none" to unassign); assigning wakes the agent

sat tasks assign <task> <agent>

sat tasks comment

Comment on a task (- reads the body from stdin)

sat tasks comment <task> <body> [options]
OptionDescriptionDefault
--kind <kind>comment | question | plancomment

sat tasks delete

Delete a task (subtasks move up to its parent)

sat tasks delete <task> [options]
OptionDescriptionDefault
-y, --yesskip confirmation

sat goals

The goal tree (alias: goal)

sat goals list

Show goals as a tree with task progress

sat goals list

sat goals create

Create a goal

sat goals create <title> [options]
OptionDescriptionDefault
--description <text>- reads stdin
--parent <goal>parent goal ("none" for a top-level goal)
--owner <agent>owning agent ("none" to clear)
--status <status>planned | active | achieved | abandoned
--target <date>target date ("none" to clear)

sat goals edit

Change a goal

sat goals edit <goal> [options]
OptionDescriptionDefault
--title <title>
--description <text>- reads stdin
--parent <goal>parent goal ("none" for a top-level goal)
--owner <agent>owning agent ("none" to clear)
--status <status>planned | active | achieved | abandoned
--target <date>target date ("none" to clear)

sat goals delete

Delete a goal (child goals move up, tasks are unlinked)

sat goals delete <goal> [options]
OptionDescriptionDefault
-y, --yesskip confirmation

sat projects

Projects and their budgets (alias: project)

sat projects list

List projects

sat projects list

sat projects show

Show a project and its open tasks

sat projects show <project>

sat projects create

Create a project

sat projects create <name> [options]
OptionDescriptionDefault
--description <text>- reads stdin
--repository <url>git repository the runner clones
--budget <dollars>
--budget-cents <cents>

sat projects edit

Change a project

sat projects edit <project> [options]
OptionDescriptionDefault
--name <name>
--status <status>active | paused | completed | archived
--description <text>- reads stdin
--repository <url>git repository the runner clones
--budget <dollars>
--budget-cents <cents>

sat routines

Recurring work on a cron schedule (alias: routine)

sat routines list

List routines and when they next run

sat routines list

sat routines create

Create a routine

sat routines create <title> [options]
OptionDescriptionDefault
--agent <agent>agent that does the work
--cron <cron>schedule, e.g. "0 9 * * 1"
--description <text>what to do each time (- reads stdin)
--project <project>
--disabledcreate it switched off

sat routines edit

Change a routine

sat routines edit <routine> [options]
OptionDescriptionDefault
--title <title>
--agent <agent>
--cron <cron>
--description <text>
--project <project>

sat routines enable

Switch on a routine

sat routines enable <routine>

sat routines disable

Switch off a routine

sat routines disable <routine>

sat routines trigger

Run a routine now: creates its task and queues a run

sat routines trigger <routine>

sat routines delete

Delete a routine

sat routines delete <routine> [options]
OptionDescriptionDefault
-y, --yesskip confirmation

sat runs

Agent executions and their transcripts (alias: run)

sat runs list

List recent runs

sat runs list [options]
OptionDescriptionDefault
--agent <agent>
--task <task>task key or id
--status <list>queued, running, succeeded, failed, cancelled (comma separated)
--limit <n>maximum rows25

sat runs show

Show a run (id or id prefix) and its transcript

sat runs show <run> [options]
OptionDescriptionDefault
--no-transcripthide the transcript

sat runs tail

Follow a run’s transcript until it finishes

sat runs tail <run> [options]
OptionDescriptionDefault
--interval <seconds>poll interval when the live stream is unavailable5

sat runs cancel

Cancel a queued or running run (a runner executing it stops)

sat runs cancel <run>

sat approvals

Decisions waiting for the board (alias: approval)

sat approvals list

List approvals (pending by default)

sat approvals list [options]
OptionDescriptionDefault
--status <status>pending | approved | rejected | allpending

sat approvals approve

Approve (id or id prefix). For budget overrides, --budget sets the new monthly limit

sat approvals approve <approval> [options]
OptionDescriptionDefault
--note <text>note for the record (- reads stdin)
--budget <dollars>new monthly budget for a budget_override

sat approvals reject

Reject (id or id prefix)

sat approvals reject <approval> [options]
OptionDescriptionDefault
--note <text>note for the record (- reads stdin)

sat runner

Execute queued agent runs on this machine

sat runner start

Claim and execute queued runs until stopped (Ctrl-C finishes cleanly)

sat runner start [options]
OptionDescriptionDefault
--agents <list>only these agents (names or ids, comma separated)
--adapters <list>only agents using these adapters (default: the ones installed here)
--concurrency <n>runs at once2
--workdir <dir>where repositories and scratch folders live (default: $SAT_WORKDIR or ~/.local/share/sat/workspaces)
--onceexecute what is queued now, then exit
--runner-id <id>identity for leases (default host:pid)
--poll <seconds>safety-net poll interval30
--on-success <status>move the task here when a run succeeds: in_review | done | nonein_review
--simulateuse the built-in echo adapter for every agent (no model calls)
--echo-delay <ms>simulated run length1500
--echo-fail-rate <0-1>fraction of simulated runs that fail0
--claude-permission-mode <mode>Claude Code permission mode: acceptEdits | bypassPermissions | plan | defaultacceptEdits
--claude-model <model>model for Claude Code
--max-turns <n>cap agent turns per run (Claude Code)
--claude-settings <file-or-json>extra Claude Code settings for agents, e.g. to let their sandbox reach the SAT API
--codex-sandbox <mode>Codex sandbox: read-only | workspace-write | danger-full-accessworkspace-write
--codex-model <model>model for Codex
--with-scheduleralso run the cron scheduler in this process

sat runner adapters

Which agent CLIs this machine can run

sat runner adapters

sat runner status

Runs in flight and queued, by runner

sat runner status

sat scheduler

Fire routines and agent heartbeats on their cron schedules

sat scheduler start

Run the scheduler until stopped (one per company)

sat scheduler start [options]
OptionDescriptionDefault
--timezone <tz>IANA time zone for cron expressions (default: this machine’s)
--expire-interval <seconds>how often to expire runs whose runner died60

sat doctor

Check the API, your sign-in, the live stream and agent CLIs

sat doctor [options]
OptionDescriptionDefault
--stream-timeout <seconds>how long to wait for the live stream20

sat completion

Print a shell completion script (bash, zsh or fish)

sat completion <shell>

CLI overview

Install the sat CLI, sign in, and learn the conventions every command shares.

Recipes

Short, tested scripts for jobs people automate with the sat CLI.

On this page

Global optionssat loginsat registersat logoutsat whoamisat apikeysat apikey createsat apikey listsat apikey revokesat profilesat profile listsat profile usesat profile setsat companysat company listsat company usesat company showsat company createsat company editsat company memberssat dashboardsat inboxsat costssat activitysat eventssat watchsat agentssat agents listsat agents showsat agents hiresat agents editsat agents pausesat agents resumesat agents terminatesat agents wakesat orgsat taskssat tasks listsat tasks showsat tasks createsat tasks editsat tasks movesat tasks assignsat tasks commentsat tasks deletesat goalssat goals listsat goals createsat goals editsat goals deletesat projectssat projects listsat projects showsat projects createsat projects editsat routinessat routines listsat routines createsat routines editsat routines enablesat routines disablesat routines triggersat routines deletesat runssat runs listsat runs showsat runs tailsat runs cancelsat approvalssat approvals listsat approvals approvesat approvals rejectsat runnersat runner startsat runner adapterssat runner statussat schedulersat scheduler startsat doctorsat completion