saggar CLI

Install the command from Settings ▸ CLI. Most control commands require Saggar to be running and must run inside a Saggar terminal.

Command	Purpose
saggar init	Create .saggar/project.json in the current project
saggar config [options]	Read or update shared project metadata
saggar config command [options] -- <command…>	Add or update a project command, including its terminal role and optional browser or Simulator surface
saggar settings [--json]	List every app preference and its stored value
saggar settings get|set|reset …	Inspect, edit, or restore an app preference
saggar hooks [--json]	Report each provider's hooks, their config file, and anything blocking them
saggar hooks install|remove <provider>	Install or remove Saggar's hooks for one provider
saggar attention [--note] "reason"	Raise a blocking claim or quiet note from this session
saggar monitor [--discreet] <command…>	Start a persistent monitor
saggar quick <command…>	Start a one-shot command beside the workspace
saggar agent <provider[.model]> <task…>	Start independent agent work in a new session
saggar agent <provider> [options] -- <task…>	Reuse or configure an agent session, including provider flags
saggar add <path>	Register a project without focusing it
saggar close <id|name>	Close an idle session
saggar list [--json]	List sessions and their stable short IDs
saggar status [--json]	Alias for saggar list
saggar read [id|name] [options]	Read bounded output from one session
saggar explain [id|name] [--json]	Say why a session wears its status
saggar wait [id|name] [options]	Block until a session settles, reaches a status, or prints a line
saggar focus [id|name]	Bring a session to the main pane
saggar approve	Answer the permission prompt in the calling session
saggar session [id|name] [--json]	Inspect a live session's name, presentation, and automatic-approval setting
saggar session [id|name] set <setting> <value>	Edit a live session setting
saggar resume show|clear|set [options] -- <command…>	Inspect, remove, or set the calling session's custom resume binding
saggar turns [--json]	List the agent turns recorded for the calling session
saggar turn <event>	Record a hook payload from stdin into the turn ledger; installed hooks call this for you
saggar <path>	Add or focus a repository
saggar help	Show current verbs and flags

Run saggar help for current option details. Commands that read terminal output may expose private material, so request the smallest useful window.

saggar wait blocks until a session is anything but working, or until the statuses named by --until (needs-you, working, idle, finished, or failed, repeatable) or a line matching --match <text>. --timeout is in seconds, 120 by default and 3600 at most; a timeout exits 1 and names the current status, and a session that closes fails the wait rather than letting a replacement satisfy it. saggar explain prints the rule that decided a session's status, such as a prompt cue, a hook claim, or recent output, with the evidence behind it. Both are reads: they never type or answer anything.

saggar settings works without a running app. Its keys match Saggar's stored preference keys; use reset to return one to its built-in default. set accepts plain strings or JSON values such as false, 0.5, or ["claude", "codex"]. Keys that widen what an agent or a paired device can do, such as self-approval, remote access, turbo defaults, and enabled providers, can be read here but only changed in Settings.

saggar hooks is the command-line form of the hook install in Settings ▸ Providers, and works without a running app. A bare saggar hooks only reads: it prints one row per provider — installed, not-installed, or no-cli — with the file an install would edit, and gathers any remaining blocker underneath, such as Codex waiting for you to trust its entries in /hooks.

install and remove each name exactly one provider; there is no bulk form. An install refuses when the provider's own CLI isn't on this Mac and names the command that installs it. Claude's install stops rather than replacing a marketplace named saggar registered from somewhere else; pass --replace-marketplace to replace it, which is the same choice the Settings pane asks you to confirm.

Dragging a session from the project menu into a chat with ⌥ held types saggar session <id> there, so a terminal can be named in a sentence to an agent; the session's ⋯ menu copies the same line.

saggar session defaults to the calling session. Its presentation setting accepts automatic, conversation, or terminal; automatic clears the live override. Setting turbo to true needs Let agents approve their own prompts turned on, and a session can never arm turbo on itself; turning it off always works. Session settings require Saggar to be running.

Workspace changes

Settings ▸ CLI ▸ CLI workspace changes controls focus, project opens, monitor, quick, agent, close, and teammate focus:

• Ask first is the default. Choose Allow or Reject in the bottom-left card.
• Allow after 10 seconds offers Allow now and Cancel, with elapsed time along the card's bottom edge. The countdown pauses while the card isn't visible in the active main window. Typing or navigating cancels the pending change.
• Allow immediately runs the action as soon as Saggar receives it.

Every completed action shows its source and result. Go back restores the previous navigation when it's still available; it doesn't reverse commands that have already run. If another attention prompt occupies the bottom-left corner, the workspace card appears beside it.

An optional reason explains the request:

saggar --reason "The test failure needs your input" focus "API tests"

The CLI waits until the action runs or is refused. Requests expire after two minutes; rejection, cancellation, and expiry exit with code 1. A second request is refused while one awaits permission. The permission setting is local to this Mac and can only be changed in Settings. Reads and saggar add don't prompt. Opening a project launches Saggar in the background before requesting consent.

Project and directory scope

monitor, quick, and agent inherit the calling Saggar session's project and recorded working directory. They identify that session through SAGGAR_SESSION; they do not use the CLI process's current directory, so a shell cd does not retarget them.

To run monitor or quick in another project, invoke it from one of that project's Saggar sessions. To start or reuse an agent session elsewhere, pass an absolute path with saggar agent --cwd /path/to/project. saggar add <path> can register another project without changing focus, but does not change the calling session's scope.

saggar approve is refused until you turn on Let agents approve their own prompts in Settings ▸ CLI. Destructive commands are held back either way.

Use --session-id with saggar agent to reuse an idle session from saggar list. --title sets its name, and --cwd chooses its working directory. Both reuse and saggar close refuse sessions that still have a running child process.

Pass provider-specific options as one quoted shell fragment with --flags:

saggar agent claude --flags '--permission-mode plan --add-dir ../shared' -- "Fix the tests"

Saggar inserts the fragment after its provider and model arguments, then safely quotes the task. The fragment is trusted shell syntax, so shell operators inside it are live.