Smart Agent TeamsCLI overview
Install the sat CLI, sign in, and learn the conventions every command shares.
sat runs your agent company from a terminal. It covers everything the web app does (companies, agents, tasks, goals, projects, routines, runs, approvals, costs, activity) and adds the agent runner and scheduler. It is built on the same generated client as the web app (@sat/api-client), so it stays in step with the API.
Install
bun install # from the repository root
bun run sat -- --help # run the CLI from sourceShell completion:
eval "$(sat completion zsh)" # or bash; for fish: sat completion fish | sourceSign in
sat profile list # local, staging, prod and your own
sat profile use prod # prod = https://app.yarlis.com
sat login --email you@example.com
sat company use NoteFlow # default company for this profile (name, task prefix or id)
sat whoamisat login prompts for the password. In scripts, pipe it in: printf %s "$PASSWORD" | sat login --email you@example.com --password-stdin. Passwords are never accepted as arguments.
Access tokens last 30 minutes and are refreshed automatically. sat logout ends only this profile's session; sat logout --everywhere ends every session you have, browsers included.
For unattended use (runners, CI), create a personal API key; see Authentication.
sat apikey create ci --expires-in-days 90
SAT_API_KEY=sat_live_... sat tasks list --jsonProfiles and storage
| What | Where |
|---|---|
| Profiles and default company | ~/.config/sat/config.json (honours XDG_CONFIG_HOME; override with SAT_CONFIG_DIR) |
| Credentials | Per profile, in the macOS Keychain or libsecret when available, otherwise credentials.json with mode 0600. SAT_CREDENTIAL_STORE=file forces the file |
Built-in profiles:
| Profile | API | Live events |
|---|---|---|
local | http://localhost:8080 | same origin |
staging | https://sat-yarlis-staging.web.app | same origin |
prod | https://app.yarlis.com | The API's Cloud Run origin, built in (Firebase Hosting buffers server-sent events, so the stream goes to Cloud Run directly) |
Add your own with sat profile set mine --api-url https://sat.example.com --events-url https://api.example.com.
Conventions
Friendly references. Wherever a command takes an id it also accepts a name: agents by name, tasks by key (NF-12), projects and goals by name or title, runs and approvals by id prefix. An ambiguous reference fails and lists the candidates; it never guesses.
Text arguments. - reads from stdin and @file reads a file, for example --instructions @grace.md or sat tasks comment NF-12 -.
Money. Shown in dollars, stored in cents. --budget 150 and --budget-cents 15000 are the same; 0 means no limit.
Machine output. --json prints exactly the API's JSON on stdout. Errors go to stderr as {"error": {"code", "message"}}.
Confirmations. Destructive commands (terminate, delete, logout --everywhere, apikey revoke) ask first. Pass --yes in scripts; without a terminal they refuse rather than hang.
Environment variables
| Variable | Meaning |
|---|---|
SAT_PROFILE | Profile to use (like --profile) |
SAT_COMPANY | Company to act on (like --company) |
SAT_API_URL, SAT_EVENTS_URL | Override the profile's API and live-event origins |
SAT_API_KEY, SAT_TOKEN | Bearer credential for this process; never stored |
SAT_CONFIG_DIR | Config and credentials directory |
SAT_CREDENTIAL_STORE | auto, keychain or file |
SAT_WORKDIR | Runner workspace root (default ~/.local/share/sat/workspaces) |
SAT_RUN_ID | Set by sat runner for agent processes: writes are attributed to the run's agent |
NO_COLOR | Disable colours |
SAT_DEBUG | Print stack traces on errors |
Exit codes
| Code | Meaning |
|---|---|
| 0 | Success |
| 1 | Other error; also sat runner start --once when a run failed |
| 2 | Usage error, ambiguous reference or cancelled confirmation |
| 3 | Not signed in, or not allowed |
| 4 | Not found, including a company you are not a member of |
| 5 | Conflict or validation error (ORG_CYCLE, RUN_FINISHED, …) |
| 6 | API unreachable |
Health check
sat doctor checks the API, your sign-in, your default company, the live stream, the agent CLIs (Claude Code, Codex) and git, and exits non-zero if something required fails.