Skip to content

CLI Reference

This page is a command index for the top-level sase CLI. It is meant for discovery and routing: use it to find the surface that owns a workflow, then follow the links to the detailed command, flag, or subsystem reference.

Compact sase --help lists only the common commands. Use sase --full-help (or -H) to print every command, then this page to route from a command to its owner guide. This page is a discovery index, not a dump of every flag. Compact help's one-line agent blurb says "active and recent"; default sase agent list (and bare sase agent) is running-only — add -a for recent DONE/FAILED.

Compact help's memory blurb still mentions reviewing proposals, but that CLI workflow has been removed. Current memory commands inspect, read, initialize, and audit memory; sase's TUI Memory panel can add/edit/delete flat notes and add/delete strands, while existing strand bodies and web descriptors are edited in $EDITOR. Agents must route all memory-file changes through /sase_memory_write first.

For exhaustive flag tables, see the configuration reference.

The root sase command accepts leading global options before the subcommand: -f/--enable-feature and -F/--disable-feature force a registered feature flag on or off for that invocation and its children, and -p/--print-command prints a shell-quoted, copyable sase ... header to stderr before running the command. The printed invocation omits only the root print switch. See the configuration reference.

Daily Operation

Command Purpose Details
sase tui Open sase's TUI, the interactive control surface for Patches, live agents, notifications, and machine services. sase's TUI
sase service Inspect and control the per-machine service host. Bare sase service shows status; service proc manages configured daemon procs and submits transient oneshots. sase service
sase scheduler Inspect or control scheduled automation. Lifecycle commands route through the scheduler service proc on the service host; bare sase scheduler shows status. Scheduler
sase screenshot Capture a canonical PNG from a real sase tui running in tmux. Use -p/--press, -T/--type, and -w/--wait-for as one argv-ordered input script, and --keep/--window to iterate against the same live TUI. Agent screenshots
sase tmux-agent Launch an interactive agent CLI in a new tmux window. A bare invocation paints a keyboard-first chooser of every registered provider; a provider name launches that CLI directly. Drop-in for bind A run "sase tmux-agent". tmux Agent
sase run [PROMPT] Launch an agent or workflow from a prompt, a macro reference, a workflow reference, history, or an editor buffer. Macros, workflows
sase pager [REF\|PATH ...] Read artifact references, file paths, or stdin in the link-traversing SASE pager; redirected stdout and --plain write plain text. SASE Pager
sase agent list List running agents. -a/--all adds recently completed DONE/FAILED agents (capped at 50 most-recent per project). sase's TUI Agents tab
sase agent search Search the complete historical agent catalog with the Artifacts → Agent Boolean dialect. The default presentation hides hidden and workflow-child rows; -p scopes one project, -l 0 removes the row cap, and -j emits a stable JSON array. sase's TUI Agent pane
sase agent show Render one agent's detail panel by name. Agent attachments
sase agent kill Terminate a running agent by name (-n/--name is required; a bare name is usage error). If the name resolves to a live monitor member or its owner, stop that monitor through the monitor path; stopped monitors do not launch their recorded follow-up. sase's TUI, Monitors
sase agent drain Relaunch agents stranded by one hard-disabled provider. The command refuses enabled and soft-disabled providers, previews with -n/--dry-run, confirms before discarding live in-flight work unless -y/--yes or -j/--json is used, accepts -m/--model for pinned agents, and reports -l/--limit drops. Exit 0 means drained or previewed, 2 refused with nothing changed, and 1 means at least one move failed after execution started. LLM providers
sase agent restart Stop a named agent and immediately relaunch its stored prompt under the same name. Deletes the previous run's artifacts (the chat transcript under ~/.sase/chats is kept). A failed wipe or relaunch writes a recovery directory under ~/.sase/restarts/. -n/--dry-run previews only, -y/--yes skips confirmation, -m/--model overrides the model, -j/--json emits one envelope and skips confirmation. Exit 0 restarted or previewed, 2 refused (nothing changed), 1 for both partial (name released, relaunch failed) and wipe_failed (stopped but the name is still taken). sase's TUI ,x
sase agent tribe Set, clear, or list user-defined agent tribes used for grouping. Agent tribes
sase agent tab Move an agent's whole presentation root between Agents-tab placements (set -n/--name -t/--tab, unset -n/--name, list [-j/--json]). Bare sase agent tab defaults to list. Moving agents between tabs
sase agent wait Block until named agents, sessions, clans, or workflows settle; -a/--all snapshots every currently running eligible agent. Exits non-zero when a target failed, is blocked on a human, or timed out. Agent wait
sase agent hold Arm, list, show, and release durable admission holds that keep matching WAITING/QUEUED agents, later launches, and undispatched procs from starting; hold run -- COMMAND holds only while one command runs. Bare sase agent hold defaults to list. Agent holds
sase agent archive Maintain dismissed-agent bundle summary indexes (rebuild-index, verify). sase's TUI
sase agent artifacts Inspect and migrate physical agent artifact storage layout. Configuration
sase agent index Manage the persistent agent artifact SQLite index (status, rebuild, verify, gc, vacuum). sase's TUI
sase agent names migrate-auto Backfill the permanent agent-name registry from legacy auto-generated names; pass --force to rerun. sase's TUI
sase agent names purge-local-state Purge every locally materialized import closure regardless of transport or source machine (artifacts, chats, dismissed bundles, identities, historical import staging, incoming-cache directories, receipts); dry run unless -a/--apply is given. Agent hood synchronization
sase agent sync Pull enabled agents sidecars, publish eligible local hoods, restore deferred prompt archives, push, and drain Referenced By write-backs; --check --refresh fetches before computing ahead/behind, while --retry-quarantined, --retry-retired (-t, requires --project), and --drop-retired handle stopped publication requests. Agent hood synchronization
sase chat list List recent chat transcripts with sync provenance; filter with -P/--provenance, -m/--machine, and -q/--query. Chat provenance
sase chat show Show one chat transcript by agent name, path, or basename; use --format resume for flattened turns or --format response for the latest response only. Chat provenance
sase prompt list List and filter previously submitted local prompts (pretty table or JSON). Prompt history
sase prompt search Search the canonical agents-sidecar prompt archive and machine-local prompt history by literal text, with date, tag, source, and cancelled filters. Prompt search
sase prompt show Print one prompt's exact text as raw, Markdown, or JSON. Prompt history
sase prompt run Replay a stored prompt by selector, optionally editing or re-prefixing it first. Prompt history
sase prompt save Save a stored prompt as a reusable macro, or export it to stdout or a local file. Prompt history, Macros
sase prompt prune Curate the prompt-history store with delete, prune, and read-only doctor/stats. Prompt history
sase prompt stash-archive List, show, and restore archived prompt drafts. A row is archived when it leaves Stash or Trash, or when an existing Stash row is updated in place. A bare invocation lists the newest rows. Draft recovery
sase stitch list Show a primary/linked timeline; --origin filters stitch/auto/manual, and --sdd opts into sidecar history. VCS
sase gate create Create a durable command-backed gate from a schema-versioned JSON specification. Notifications
sase gate show Inspect a gate's branches, declared typed inputs, and repeatable actions without answering it. Notifications
sase gate answer Answer a gate headlessly, including per-option typed input, resume/restart of a partially executed branch, and resume of an already-answered turn whose requested follow-up never launched. Notifications
sase gate act Run one gate-declared repeatable action without settling the gate. Notifications
sase gate wait Wait mechanically for a command-backed gate and return its terminal result. Notifications
sase gate list List pending gate-turn session members; --all includes settled history. Notifications
sase gate cancel Cancel a pending gate turn by id, prefix, member name, or owning agent. Notifications
sase sudo request Create a typed sudo gate from one JSON batch of exact argv commands on stdin; an agent caller hands its turn to the gate turn. Every sase sudo subcommand requires the agent_sudo_requests beta flag. Sudo requests
sase sudo list / show List pending sudo gate turns (-a adds settled ones), or show one request's reviewed commands. Bare sase sudo defaults to list. Sudo requests
sase sudo answer Approve (-u/--run or -a/--approve) or deny (-d/--deny) one sudo gate; with neither, an interactive terminal asks. Approval needs a controlling terminal and authenticates through the host's real sudo prompt; -c selects reviewed command ids; -r/-R are accepted for parity with sase gate answer but do not skip commands that already ran. Sudo requests
sase notify Shortcut for sase notify list. Notifications
sase notify +1 Append a corroboration note by notification ID/prefix or sender-scoped dedup key without changing inbox state. Notification +1 evidence
sase notify create Create a raw, non-privileged notification from JSON input, or atomically append evidence to a matching dedup key. Notifications
sase notify list List recent notifications, optionally filtered by sender, tag, unread state, or query. Notifications
sase notify rules Show the merged notification delivery rules in evaluation order, or explain one notification's toast and sound with -e ID. Delivery Rules
sase notify show Show one notification as Markdown or JSON. Notifications
sase proc Shortcut for sase proc list. sase's TUI Procs tab
sase proc list List durable procs; filter by session, project, tag, status, or query. sase's TUI Procs tab
sase proc run -- COMMAND Run a durable command proc; --session none leaves it unattributed, and --wait streams it and returns its exit code. sase's TUI Procs tab
sase proc show REF Show one proc (by named proc, id, or unique id prefix) and its captured output; --follow streams until it finishes. sase's TUI Procs tab
sase proc kill REF Kill a running proc by named proc, id, or unique id prefix; an already-terminal proc is an unchanged no-op. sase's TUI Procs tab
sase repro replay Replay an Agents-tab reproduction bundle through the headless TUI harness and emit a verdict. sase's TUI
sase repro capture agents-tab Capture a commit-safe out-of-band Agents-tab bundle from current filesystem state. sase's TUI

sase stitch list --origin ORIGIN accepts stitch, auto, or manual; repeat the flag to OR multiple origins. sase stitch list --format json includes the same canonical value as each commit's "origin" field.

sase run launches detached background agents that appear in sase's TUI Agents tab. It can start from prompt text, macro or workflow references, the editor, or the prompt-history picker, and multi-prompt input expands into sequential background launches. sase's TUI uses the same launch machinery when users start agents from the TUI. When sase run is used from an interactive terminal (not from inside an agent or a durable proc) and its %hold preview is broad, it prints the preview and asks Arm this hold? [y/N]; declining cancels the launch and exits 1. A host-scoped hold that includes future is always broad. A pending hold is broad when its live capture exceeds agent_hold_confirm_capture_threshold, but that check needs project context: typed launch plans can resolve it, while a plain project-scoped sase run prompt currently cannot and therefore skips this confirmation. Once accepted, the launch submission pre-arms the hold before admission can race ahead, then rebinds ownership to the launched runner. Narrow and non-interactive holds use that same pre-arm path without the extra prompt.

The short option -n is not one flag across commands: sase agent kill -n NAME and sase agent hold create -n NAME are --name (for kill it is required; a bare name is a usage error), sase agent drain -n and sase agent restart -n are --dry-run (the agent name or provider is positional), and sase monitor start -n is --next. Likewise, sase agent wait -a is --all: it snapshots the eligible agents running when the wait starts, while sase agent list -a means include recent completed agents in a list view. sase agent hold create -p is --pending, not --project.

sase agent search [QUERY ...] browses the complete historical catalog used by Artifacts → Agent, rather than the live operational rows returned by agent list. Queries use AND, OR, NOT, parentheses, free text, and the Agent pane's identity, lineage, lifecycle, time/runtime, and artifact-link fields. For example:

sase agent search 'revivable:true AND project:sase AND role:code'
sase agent search 'provider:codex AND status:FAILED AND since:7d'
sase agent search 'linked:true AND relation:read'

A bare search applies the default presentation scope: hidden rows and kind:workflow-child rows are omitted unless the query explicitly asks for them. The default cap is 40; -l 0, --limit 0, or limit:all removes it, and an explicit -l/--limit overrides a limit: token inside the query. -p/--project accepts a project key, alias, or display name. Options may appear before or after the query, and -j/--json emits a stable array.

sase agent wait

sase agent wait NAME ... resolves each target the same way %wait does: clan, then agent session, then workflow, then exact agent name. A session target waits on the whole session, including successors that appear after the wait begins. sase agent wait -a waits for every eligible agent running at command start and deliberately does not absorb later unrelated launches; when run from inside an agent it excludes the calling agent's own session so -a cannot wait on itself. -p/--project scopes target resolution and the --all snapshot to one project.

By default the command stops when a target cannot progress without a human: a pending question, a submitted plan awaiting review, or a stopped artifact with no completion marker exits 3. Use -w/--wait-blocked only when you want the gate to keep polling through those states. -t/--timeout exits 4 if unfinished targets remain after the duration, and -i/--interval pins the poll interval instead of using the adaptive default.

Exit codes are 0 when every target succeeded, 1 when any target finished unsuccessfully, 2 for command usage or resolution errors, 3 for human-blocked targets without -w, 4 for timeout, and 130/143 for SIGINT/SIGTERM. Precedence is 1 > 3 > 4 when more than one condition applies.

Progress output goes to stderr. The final settle summary goes to stdout, and -j/--json prints one stdout JSON envelope with no progress noise, so gate JSON and command substitution both stay predictable.

sase agent list -j reports every live runner-slot waiter as status: "QUEUED", whether it is waiting on the global budget or an authored %queue(capacity=N) weighted-load threshold. Its queue_weight reports requested capacity units, and runner_slot_queue_position/runner_slot_queue_size rank the same waiters in the capacity-aware display order used by sase's TUI: eligible waiters first, then parked waiters by current blocker severity, with priority and request FIFO preserved inside each group. A waiter parked by an agent hold also reports the blocking hold's armer in held_by and that hold's expiry in hold_expires_at. Each entry also exports the epic-follow state: wait_for_epics_of (armed follow targets) and epic_follows (per-target launching / following / blocked stages with epic_ids, added_bead_ids, and blocker details). sase agent wait rows use the same shared phrasing (↪ waits on <target>'s epic <id>) as the TUI lanes.

sase agent hold

An agent hold is a durable, reverse-wait admission barrier: while it is active, matching agents stay WAITING or QUEUED instead of starting, and matching procs that have not been dispatched yet stay pending. sase agent hold is the standalone CLI for the hold store that the %hold directive also describes in prompt text. The CLI and directive are available without a feature flag. Use the CLI when you need to inspect, release, or arm a hold outside a launch prompt.

sase agent hold create -n planner -t nightly   # block one name plus a tribe
sase agent hold create -f -s host -T 45m       # fence every later launch on this host
sase agent hold run -- just check-full         # quiesce while one command runs
sase agent hold list -j
sase agent hold show -k cli:myhost:12345
sase agent hold release                        # release this shell's or agent's own hold

create requires at least one selector: positional SELECTOR arguments (a name, or an @tribe, expanded the same way as %hold names and tribes), repeatable -n/--name (an agent, agent session, clan, workflow, or named proc name; role-suffixed names stay exact), -t/--tribe (with or without @), and -H/--hood, plus -f/--future (agents and undispatched procs submitted after the hold is armed) and -p/--pending (freeze the WAITING/QUEUED agents in scope right now; it does not capture undispatched procs or later launches). -s/--scope is project (the default, inferred from the current checkout or agent) or host. -T/--ttl accepts bare seconds or a single-unit duration such as 90s, 45m, or 2h (compound values like 1h30m are accepted only by %hold(ttl=...), not by -T); it defaults to agent_hold_default_ttl (2h) and may not exceed agent_hold_max_ttl (12h); see agent hold limits. Arming, releasing, and TTL expiry post notifications; the expiry notice includes the exact boundary. sase's TUI Admin Center lists and releases active holds.

Each armer owns one hold. Inside an agent run the armer is that agent (agent:<name>), and the hold is dropped once the agent's session settles. From a plain shell the armer is cli:<machine>:<pid> anchored to the parent shell, so the hold lasts until it is released, its TTL expires, or that shell exits. sase agent hold release releases the calling agent's or shell's own hold unless -k/--key names another armer key, and exits 1 when no such hold is active. sase agent hold show -k KEY prints one hold, including its frozen pending artifact directories and launch-time capture summary (-j prints the raw record), and exits 2 when the key has no active hold. Older records without that evidence display “capture not recorded.”

sase agent hold run [selectors] -- COMMAND arms a hold anchored to the run process, runs COMMAND, releases the hold on success, failure, or interruption, and exits with the command's status. With no selector flags it defaults to -f -p, the selector-free quiesce recipe. Holds whose armer has died or whose TTL has passed are pruned whenever the store is read.

sase service

The service host supervises machine-level daemon procs independently of the TUI that started them. Bare sase service is read-only and delegates to sase service status; bare sase service proc delegates to proc list.

sase service status
sase service start
sase service proc list
sase service proc restart scheduler
sase service proc run -- just check

start, stop, and restart control the host; run intentionally owns the foreground terminal. logs -n N prints the bounded host log. status -j emits the host and every configured proc as JSON and exits 0 while the host is running or starting, otherwise 1. When a native unit is installed, lifecycle commands use that platform manager; otherwise start uses the detached host path.

sase service status prints the host summary (plus the host config error when one is set) and a proc table with Restarts and Last exit columns; the proc State column is colored by the same severity vocabulary as the Services tab (crash_loop and backoff fail, exited fails while desired running (a clean give-up only warns), unavailable warns, disabled and operator-stopped are muted). Below the table it repeats the blockers and warnings sase service init would report, such as provider CLIs missing from the captured PATH, a refused or login-session-only GitHub credential, and service procs whose executable cannot be found.

When service.procs stops loading (for example a YAML error in a machine overlay), the host keeps supervising its last-known-good configuration and reports the load error as Host error: until the configuration loads again; running procs are not stopped because the new configuration is unreadable. A proc the restart policy gives up on — a clean exit under restart: on-failure, or any exit or spawn failure under restart: never — is parked: the host stops relaunching it and it stays exited with its last exit until sase service proc start NAME or restart NAME revives it, or its configuration changes. A proc that enters a crash loop, or a desired-running proc that is parked, raises a service notification naming the reason, restart count, and log path; a parked proc's notification also names the reviving sase service proc start NAME command.

sase service proc list carries the same Restarts and Last exit columns and additionally exposes effective configuration, machine enablement, desired state, runtime state, source, launcher, and log path. show NAME reports uptime, the restart count, the last exit and when, the current restart decision reason, stop provenance, the description, and any pending start/restart request. start NAME and restart NAME record a durable request that the host consumes, then wait for the host to confirm it: a restart prints service proc NAME restarted: pid OLD -> pid NEW, a start prints service proc NAME started: pid N (or already running: pid N), and either exits non-zero when the host cannot confirm, the proc is disabled or unavailable, or the host is not running. A start or restart request also clears this boot's stop marker. -n/--no-wait returns as soon as the request is recorded and -t/--timeout SECONDS bounds the wait (default: the proc's stop timeout plus 10 seconds, at least 15). stop NAME stops the proc until the next boot; enable NAME and disable NAME persist a machine-local override. logs NAME prints that proc's bounded log. A configured proc that is invalid remains visible as unavailable rather than preventing unrelated entries from running.

sase service proc run -- COMMAND... submits a transient oneshot through the durable proc service. It does not add the command to daemon desired state and the host never replays it after restart. It runs outside the service host's process tree, records its exit code, and appears in the Services tab's oneshots section under a #1–#9 index; at most nine can be running at once, and finished ones never count. The TUI's !! background commands use this same path. -c/--cwd, -l/--label, -p/--project, and -w/--workspace add attribution; -j emits the created proc record.

Install or inspect the native user unit with sase service init. Without --yes it prints a plan; --check is read-only and exits non-zero on drift, --diff includes the unit and redacted captured-environment diff, and --yes applies. Linux uses a systemd user service and macOS uses a LaunchAgent. A non-default SASE_HOME requires --force, which creates a home-scoped unit identity. sase service uninstall has the same plan/check/diff/apply shape; --force is also required when uninstalling the non-default-home unit. See service configuration and initialization.

sase proc operates on durable procs: rows in ~/.sase/procs/procs.jsonl with combined output logs under ~/.sase/procs/logs/. New sase proc run submissions always create command rows under a supervisor; --session only controls attribution, and --session none records an unattributed command visible in every session scope. Historical detached rows remain readable and controllable. sase task is still accepted as a deprecated alias.

The supervisor is independent of the submitting shell or TUI, so command work survives TUI restarts and runs with no TUI open. The compact list markers are ⌘ for command, ▣ for tui, and ◆ for historical detached rows; sase proc show spells out the kind and ownership. Use sase proc kill REF to stop any active store-backed proc. JSON output uses a procs array for list and a proc object for run, show, and kill. Retention keeps every pending or running proc plus the newest procs.history_limit finished ones. See the sase's TUI Procs tab for the full model and the in-TUI equivalents.

sase proc run -N/--name NAME and sase proc list -N/--name NAME address a proc by a named proc instead of its id: a bare name is derived beneath the calling sase-agent (outside a sase agent a bare name is an error), while a fully qualified name (<agent>--<name>; names may not contain /) is resolved exactly before falling back to an exact proc id, then a unique id prefix. Active uniqueness is scoped per project, and a name may be reused only after the proc holding it settles. sase proc show REF and sase proc kill REF accept the same named proc, id, or id-prefix forms (an id prefix needs at least three characters).

Every command group with an exact list child defaults to that list view when invoked bare — sase agent, sase agent-cli, sase artifact, sase bead, sase chat, sase completion, sase disk, sase file, sase file-history, sase file-hook, sase final, sase flag, sase gate, sase goal, sase instructions, sase machine, sase memory, sase migrate, sase monitor, sase notify, sase plan, sase plugin, sase proc, sase project, sase prompt, sase repo, sase skill, sase snippet, sase stitch, sase sudo, sase telemetry, sase tool, sase usage, sase var, sase workspace, and sase macro. Nested groups such as sase agent hold, sase agent prompts, sase agent tribe, sase artifact link, sase artifact link relation, sase artifact trash, sase axe job, sase axe routine, sase bead dep, sase bead ref, sase bead task-type, sase memory web, sase patch ref, sase plan links, and sase project alias follow the same rule. A bare invocation prints a short notice naming the delegation, for example No subcommand provided for 'sase repo'; delegating to 'sase repo list'. Groups without a list child, such as sase patch, sase axe, or sase bead pages, do not delegate.

This is a property of the parser, not a hand-maintained list: any group that gains an exact list child picks the behavior up automatically.

The bare form is only the default view. When you need flags that belong to the list command, keep the list subcommand explicit, for example sase notify list -j, sase agent hold list -j, or sase workspace list --json.

Work Tracking And Planning

Command Purpose Details
sase patch current Render the Patch associated with the current workspace. Patches
sase patch ref List, attach, or detach durable artifact references on a Patch; the bare command defaults to ref list. Patch references
sase patch migrate-extension Rename legacy .gp ProjectSpec files to the canonical .sase extension. ProjectSpec
sase patch search Search and filter Patches with the query language. Query language
sase patch set-origin Mark a Patch's PR_ORIGIN (sase/external/unknown). PR_ORIGIN
sase patch sync-deltas Recompute the DELTAS field for a Patch from VCS state. Patches
sase patch sync-external Mirror remote PRs not created by SASE's tracked PR workflow into local Patches. Axe external PR mirror
sase init Check and initialize config, machine, memory, repositories, the optional service host, and skills. Initialization
sase init --all --check Check every enabled main project without writing; report one aggregate status. Initialization
sase init --all --yes Initialize every enabled main project without generic prompts; sidecar creation still asks. Initialization
sase init -p NAME Check or initialize named enabled projects as one process; repeat -p for a subset. Mutually exclusive with --all and -M. Initialization
sase init --check --json Emit one schema-versioned JSON plan (current / drift / blocked) instead of Rich output. Initialization
sase machine Discover, enroll, verify, repair, and operate remote dispatch machines. Remote Dispatch Runbook
sase init machine Compatibility alias for sase machine init. Initialization
sase memory / sase memory list Show loaded, referenced, available, and missing memory files. Memory
sase instructions / sase instructions list Inventory project, home, and chezmoi AGENTS.md files plus nearby provider shims. Initialization
sase instructions verify Show observed instruction loads per provider from the providers' own session records; -c adds manifest coverage, -a adds the intended-vs-observed section diff, -j emits versioned JSON. Reports only, never gates. Providers
sase instructions render Preview the memory-built bundle for the current project and home without delivering it; -j emits the preview manifest, -s the section table, -p checks legacy parity. Instruction Bundles
sase memory show Print one or more memory selectors (a note, a bare web, or web:keyword) without recording an audited read. Memory
sase memory read Agent-side read of one or more memory selectors with an attributable audit event; -r/--reason is required. Memory
sase memory log Summarize audited memory reads; --include glossary folds in legacy pre-web glossary reads. Memory
sase memory history Show the cross-file changes feed with no selector, or per-subject timelines with selectors; -A/--at pins one version, -d/--diff shows the change instead of the body, and -f json emits the wire unchanged. Viewing history never records an audited read. Memory History
sase memory init Refresh home and SASE-managed project memory; copy existing AGENTS.md files to provider instructions. --check reports drift and untracked or gitignored managed files. After a committing deploy, an additional guard reports managed files still untracked or dirty; see the guide for scope and Git-error handling. Initialization
sase init memory Alias for sase memory init. Initialization
sase memory web / sase memory web list List discovered memory webs: slug, scope, strand count, and description. Memory Webs
sase memory web show WEB [PATTERN] Print one web's filterable strand index (keyword, aliases, reference count, summary); never strand bodies. Memory Webs
sase repo init Initialize configured sidecars, generated guides, config, and repository ignores. Initialization
sase init repo Alias for sase repo init. Initialization
sase repo path REPO Print a primary or sidecar path; --ensure materializes the selected sidecar. SDD Storage
sase plan links [list] Inspect prompt/plan artifact links; bare links defaults to list. SDD
sase plan links refresh Preview reconciliation of generated plan header sections (PARENT, BEAD, AGENTS, COMMITS); -w/--write applies and commits it, -P/--plan REF scopes it to one plan. SDD
sase plan links repair Infer and optionally write missing bidirectional SDD links. SDD
sase plan links validate Validate SDD artifact links. SDD
sase bead onboard Print the bead quick-start guide. Beads
sase bead init Initialize bead storage for the current project. Beads
sase bead create Create plan, epic, phase, or standalone task issues. Every create requires -w/--reason. Beads
sase bead +1 Corroborate an existing task with one reporter's independent evidence (-S allows sensitive attachment paths). Beads
sase bead list List bead issues by status, type, tier, or creation date. Beads
sase bead search Search bead IDs, titles, notes, plan paths, metadata, and lifecycle fields; --regex enables regular expressions. Beads
sase bead pages Refresh generated bead pages or print one bead's hosted page URL. Beads
sase bead ready Show task beads marked ready whose dependencies are closed. Beads
sase bead blocked Show issues blocked by active dependencies. Beads
sase bead show Show one or more issues; full IDs can route to another enabled project's bead store, -P/--project pins one store, <epic-id>.. expands direct children, and long output can use the shared SASE Pager. Beads
sase bead read Read one or more beads with show-identical output after recording an audited read with -r/--reason; agents must use it (show refuses agent runs). Beads
sase bead update / open / close / rm Mutate issue metadata or lifecycle state (-S allows sensitive attachment paths on -n). Beads
sase bead snooze Defer a task bead until a wake time or a +1 threshold; --cancel clears an existing snooze. Beads
sase bead note Append an attributed note (@<path> attaches a snapshot; -S allows sensitive paths), rewrite note N with -e N, or retract it with -x N. Beads
sase bead attach Attach file snapshots to a bead as a new attributed note (-n prose, -N rename, -S allows sensitive paths). Beads
sase bead attachment list List attachment snapshots on one bead (-j/--json for machine-readable output); bare sase bead attachment delegates to list. Beads
sase bead attachment path Print the absolute local view path for one attachment, or a clear unavailable error; fetches from the shared store when needed. Beads
sase bead attachment open Open one attachment in the terminal viewer; fetches from the shared store when needed. Beads
sase bead attachment push Drain the upload outbox and promote local-only objects to the shared stores. Beads
sase bead attachment purge Purge one attachment's bytes behind tombstones (-r reason required, -y skips confirmation); notes render (purged). Beads
sase bead attachment prune Prune the local attachment cache to its budget (dry run by default, -y evicts); never evicts pending or local-only objects. Beads
sase bead attachment publish Widen one note attachment to public (human-only; -y skips confirmation); appends NoteEdited with the note text unchanged. Beads
sase bead attachment unpublish Narrow one note attachment back to private (withdraws the public object; no tombstone); appends NoteEdited with the note text unchanged. Beads
sase bead doctor --fix-attachments Repair attachment orphans, re-drain the upload outbox, and quarantine corrupt objects. Beads
sase bead ref List, attach, or detach durable artifact references on a bead; the bare command defaults to ref list. Beads
sase bead history Show event history or find overwritten notes. Beads
sase bead task-type Inspect the effective task-type catalog (list / show). Beads
sase bead touched List beads one agent touched, newest first, one row per bead. Beads
sase bead sync-external Mirror external tracker issues into task beads. Beads
sase bead resolve-conflicts Resolve mechanical git conflicts in bead event streams. Beads
sase bead dep List (list, the bare default), walk (tree), add, or remove issue dependencies. Bead dependencies
sase bead sync Regenerate the JSONL projection from canonical events and stage bead state. Beads
sase bead stats / doctor Inspect project statistics or bead-store health; doctor can repair projections, issue-prefix drift, legacy design refs, and recoverable missing plan archives. Bead doctor
sase bead work Launch one or more plan, epic, or task targets in order; --wait holds launched epic phases. Beads
sase goal / goal list List unsettled goals; bare sase goal defaults to list. -s/--status filters (done, dropped, settled, and all scan history, newest first), -a/--all-projects renders one section per project, -f/--fresh integrates first, -j/--json emits GoalListWire. Goals
sase goal show Show one goal card by id (⌖-prefixed, goal:-prefixed, or goal:<project>@<id> forms accepted); -j/--json emits GoalStateWire. Goals
sase goal new / edit / drop / reopen / merge Create, reshape, or settle goals. Human verbs: refused inside agent runs. Goals
sase goal doctor Check the goal ledger; -r/--repair fixes markers and rebuilds the projection (human only). Goals
sase project list List enabled projects by default, or inspect disabled/internal backing records with --state. Project lifecycle
sase project current Show the current project derived from the VCS macro MRU, colored by project accent; --json for machine-readable output. Current project
sase project show Show lifecycle, workspace, launchability, and warning details for one project. Project lifecycle
sase project enable / disable Apply the normal user-facing PROJECT_STATE transitions under lock. Project lifecycle
sase project set-current Promote a project to the VCS macro MRU head, making it current; --json for machine-readable output. Current project
sase project set-state Set a lifecycle or internal backing state under the ProjectSpec lock. Project lifecycle
sase project alias List, add, remove, or clear PROJECT_ALIASES under the ProjectSpec lock. Project names
sase plan / sase plan list Show pending proposals, recent approvals, and inferred rejected archived proposals. Macro directives
sase plan approve Approve a pending proposal or a plan file with no live gate. It defaults to a tale (epic plans require an explicit kind); --dry-run previews and --project identifies a gateless plan's project. Re-approving an approved plan relaunches a failed, killed, or never-launched coder and refuses one that is running or finished. Plan approval pipeline
sase plan propose Submit a plan file for approval from the plan skill path. Macro directives
sase plan reject Reject one pending plan by name (TAB completes), <shard>/<name>, path, plan: ref, planner agent, or notification ID/prefix, then attempt planner cleanup when found. Macro directives
sase plan search Search or browse resolved-store SDD artifacts (tale and epic plans, prompts, and document-sidecar roles such as research) plus the machine-local plan archive by literal text and metadata. SDD
sase plan show [TARGET] Resolve a path, plan: reference, pending-approval selector, slug, or bead id to one plan and render it as a detail view, compact row, JSON, or raw text. SDD
sase plan validate PLAN_FILE Validate one explicit plan path against the schema selected by its authored tale or epic tier; -e/--explain prints authoring guidance and -j/--json emits diagnostics. SDD
sase launch request Register a launch gate and print its descriptor; agent callers then hand off to a gate turn. Agent groups
sase launch approve / reject Resolve a pending launch request by request id, notification id, or unique prefix. Agent groups
sase questions Ask structured user questions from the questions skill path. Macro directives

Patches are PR-sized review records. SDD stores durable prompt and planning artifacts. Beads add git-portable dependency tracking and executable epics on top of those artifacts.

Bead commands that take existing bead IDs — show, update, open, close, rm, note, +1, snooze, history, dep, ref, pages, epic-symbols, and work — resolve a full ID against the current project's store first and then route it to the enabled project that owns it, so sase bead close bob-cli-1e --note done works from another project. Shorthand suffixes stay local, mutating commands reject batches that span more than one store before writing, and sase bead create places a child in the store that owns a full parent ID. Commands without a bead selector (list, search, ready, blocked, and stats) keep the current-project scope. See Bead ID Arguments.

sase project defaults to sase project list, and sase project list defaults to enabled true projects. sase project current prints the current project derived from the VCS macro MRU head — the project name in that project's accent color, its canonical directory key, whether it came from a project ref or a Patch, and the MRU ref that produced it. Launch an agent on a project (or on a Patch owned by that project), or run sase project set-current, to change it — sase's TUI binds the same operation in the Projects tab. When nothing resolves, the command explains that and exits 0. Use sase project list --state all --json to inspect disabled projects and internal sibling backing records, sase project disable <project> to hide a dormant project from default launch views, and sase project enable <project> to make it launchable again. Disabling refuses projects with live RUNNING claims or active artifact markers unless --force is passed. Project arguments also accept the project tag spelling, so sase project show +sase works like sase project show sase. sase project list has a TAG column and sase project show a Tag: line with each project's +<name> spelling (- or omitted when the name does not fit tag syntax), colored by project accent on a color terminal; their --json output adds tag (null when the name does not fit tag syntax), workflow_type, and accent (null for disabled projects). Legacy active/inactive values and the deprecated lifecycle command aliases remain read-compatible. sase's TUI Projects tab (in the SASE Admin Center, opened with #) provides the interactive counterpart, including marking multiple projects, editing a ProjectSpec in $EDITOR, and deleting obsolete SASE project directories after confirmation. There is no CLI delete subcommand; full project-directory deletion is only available from sase's TUI Projects tab and removes state under ~/.sase/projects/, not workspace checkouts.

sase project alias list [PROJECT] [-j|--json], add PROJECT ALIAS, remove PROJECT ALIAS, and clear PROJECT manage ProjectSpec aliases. sase's TUI Projects sub-tab (in the SASE Admin Center, opened with #) also displays aliases, includes them in filtering, and opens an alias editor with A. Alias refs are accepted in launch-bound VCS workspace tags, but prompt history, agent metadata, and artifacts use the canonical directory-key project name. ProjectSpecs may also carry PROJECT_NAME as the primary user-facing name. For example, the GitHub provider can create PROJECT_NAME: foo and then PROJECT_NAME: foo_1 for distinct owner/foo repositories while keeping stable canonical project records. Existing auto-aliased GitHub projects remain valid and keep resolving through PROJECT_ALIASES.

Enabled-only true-project discovery is also the default for launch pickers, Patch searches, project-local macro catalogs, broad mobile helper catalogs, and all-known bead helper reads. Internal sibling backing records are hidden from those surfaces and support configured linked repositories. Agents prepare one through /sase_repo; the underlying audited open infers the host project and workspace from cwd. Agent-history views that need older artifacts opt into all project states explicitly. An explicitly typed known-project VCS ref is a launch-time exception: it re-enables a disabled project before claiming a workspace. A checkout cwd or mobile project value is only prompt-resolution context, not a workspace ref; without an explicit ref, a bare prompt defaults to #git:home. Direct low-level claims against a disabled ProjectSpec remain blocked until the project is enabled.

sase plan defaults to sase plan list. The dashboard has Proposed, Approved, and Rejected sections; use repeatable -s/--status options to select sections, -n/--limit to set each history section's size (0 is unlimited), and -t/--tier to filter by plan-file tier. Proposed rows are never limited and are the actionable rows; each leads with the plan name in bold cyan (shortest unique form, with the dim id_prefix below it), plus agent, project, provider/model, plan path, and response directory. A hint line under the section shows the ready-to-paste approve/reject commands for the first name. Pass the plan name to sase plan approve <name> or sase plan reject <name> (a <shard>/<name> path, filesystem path, plan: ref, planner agent, or notification ID/prefix works too; names TAB-complete). Proposed --json rows carry the same name field. If the selector is omitted, exactly one pending proposal must exist. When --kind is omitted, approval follows the plan's authored tier; an explicit kind overrides it. The Rejected section is inferred from archived proposal files that are not represented by the proposed or approved state; it is a history aid, not the selector source for new actions. The approval kind is the workflow choice: approve runs the coder without asking the runner to commit an SDD plan, tale commits the plan as an SDD tale and then runs the coder, epic commits the matching SDD tier and launches the bead follow-up, and commit records the approved plan in SDD without launching a coder. Use -m/--model to pick the follow-up agent's model. Use -p/--prompt to add extra coder instructions for the approve and tale paths. A plan with no live gate can be named by path, plan: reference, archive name, or unavailable gate ID: it is approved directly and starts a #coder in the planner's agent session when it can safely attach, otherwise as a standalone agent. -n/--dry-run renders that decision without changing state, and -P/--project supplies project context for the direct route. Re-approving an already-approved plan relaunches its coder when that coder failed, was killed, or never launched, and refuses when the coder is still running or has finished. Tale and epic approvals validate against their target schema before writing a response; a failure prints the diagnostics and expected schema and leaves the proposal pending for retry. Plans can also declare typed choices and toggles as Plan Decisions. Ordinary approval accepts their effective defaults; pass -D/--decide ID=VALUE to approve with different values, or use sase gate answer with --set decision_<id>=<value> to override them on a pending gate. See Plan Decisions for the grammar, memory-consent rules, and current interface limits.

sase plan reject writes the rejection response first, then uses the same durable cleanup path as the TUI no-feedback rejection action when the matching planner row is still discoverable. If cleanup cannot find or kill the row, the CLI reports that separately after the plan has already been rejected.

sase plan search [QUERY] searches plans in the resolved SDD store (the repo source) and the machine-local ~/.sase/plans/ archive. Omit the query to browse with metadata filters. Compact and Markdown output group SDD-store matches above local matches; JSON and full output keep ranked result order with SDD-store matches prioritized over otherwise-similar local matches. Useful filters include --kind, --status, --source, --since, --until, --sort, and --format json|markdown for agent-friendly output.

sase plan show [TARGET] resolves any way a user can name a plan to exactly one plan and renders it. In -t auto (the default), TARGET is tried against five rungs in order and the first definitive match wins: path (an existing file, absolute or cwd-relative), ref (a plan: reference, a legacy marker path, or a month-drifted reference, Rust resolved), proposal (any pending-plan selector approve/reject accept: name, <shard>/<name>, planner agent, or notification id/prefix), name (a corpus slug or <shard>/<slug> lookup, with or without .md), and bead (a bead id whose design field points at a plan). Pass -t/--target to force one rung with no fallthrough. Omit TARGET to show the sole visible pending plan proposal, exactly as sase plan approve/reject treat an omitted selector. Every ambiguity prints its candidates as re-runnable plan: references and every miss prints close-match suggestions; neither guesses. -f/--format selects full (the default section-structured detail view, matching the PLAN lane in sase's TUI), compact (the same row sase plan search prints), json (a schema-versioned envelope), or raw (the plan file's exact text, for piping). A plan that fails validation still renders in full with its diagnostics shown and exits 0; only a missed, ambiguous, or unreadable target exits 1. -w/--wrap controls goal/phase/diagnostics prose wrapping, and -c/--color matches sase bead show.

sase plan validate PLAN_FILE reads the required tier: tale|epic property and validates exactly one path without requiring a project or agent context. With Plan Decisions, agent-context validation also checks memory selectors and human-request quotes; outside an agent, quote verification is deferred to proposal. It reports every schema problem in one run and prints the expected tier schema plus a minimal valid example on failure. Use -e/--explain for tier-specific authoring guidance, -j/--json for the stable machine-readable envelope, or -q/--quiet to suppress the successful human summary. A plan that has decisions also prints the Decision Sheet after the result, and, when the live %auto spelling covers the plan's tier, auto-approved: every decision takes its default. When the spelling does not cover the tier, sase prints %auto:<mode> does not cover <tier> plans; this plan waits for review instead. In --json mode stdout stays one JSON document: the sheet, the %auto note, and the outside-agent quote-verification note live inside the decisions envelope while the same human text goes to stderr. See the validation output. The removed -t/--tier option is now invalid command usage. A valid plan exits 0, a validation failure exits 1, and invalid command usage exits 2.

sase goal

Goals are durable records a person creates, lists, shows, edits, drops, reopens, and merges. Bare sase goal defaults to sase goal list, which shows unsettled goals with an honest freshness header (synced Ns ago, local only, or never synced) and footer chips (↑ unpublished, refreshing…, ⚠ N unreadable). -s/--status filters the list; done, dropped, settled, and all scan history newest-first with -n defaulting to 20. -j/--json emits the wire structs the gateway consumes. new, edit, drop, reopen, merge, and doctor --repair are human verbs and refuse inside agent runs; list, show, and doctor work everywhere. See Goals for the full tour.

Automation

Command Purpose Details
sase scheduler [status] Inspect the scheduler through the scheduler service proc. Scheduler
sase scheduler start Start the scheduler service proc. Scheduler
sase scheduler stop Stop the scheduler service proc. Scheduler
sase scheduler restart Restart the scheduler service proc. Scheduler
sase scheduler run Run the scheduler orchestrator in the foreground. Scheduler
sase axe start Alias of sase scheduler start. Scheduler
sase axe stop Alias of sase scheduler stop. Scheduler
sase axe restart Alias of sase scheduler restart. Scheduler
sase axe status [--json] Alias of sase scheduler status: the scheduler service proc's status in human or JSON form. Scheduler status
sase axe job list List configured jobs with status; -a adds scripts. Axe jobs
sase axe job doctor Diagnose configured/available jobs and Telegram setup. Axe jobs
sase axe job run <name> Run one job in the foreground; -n previews agent proposals, -f bypasses declarative guards, and -L names the routine. Axe jobs
sase axe routine list List configured routines. Axe routines
sase axe routine run <name> Run one routine in the foreground for debugging. Axe routines
sase axe routine status Show routine process status. Axe
sase axe maintenance enter Pause scheduled routine ticks with a recorded reason. Maintenance mode
sase axe maintenance exit Resume scheduled routine ticks. Maintenance mode
sase axe maintenance status Inspect the maintenance marker. Maintenance mode

The scheduler runs scheduled hooks, mentors, comment polling, workflow checks, %wait dependency resolution, cleanup, and error digests. sase's TUI starts the service host unless launched with sase tui --no-service (--no-axe). sase axe start|stop|restart|status is an alias of the matching sase scheduler command. The older sase axe chop ... and sase axe lumberjack ... spellings remain hidden compatibility aliases for sase axe job ... and sase axe routine ...; see Compatibility aliases.

Command Purpose Details
sase monitor start Hand a command to a detached supervisor and return; kills the caller. -p/--profile verify supplies verification outcome defaults; -P/--policy loads a JSON/YAML outcome policy, -k/--checkpoint binds durable handoff state, and -f/--completion binds a prepared host-completion intent. Pass the command after --; -n/--next, -m/--model, and -o/--next-output control ordinary continuations. Monitors
sase monitor list List monitor session members, newest first; bare sase monitor defaults here. Monitors
sase monitor show Show one monitor's detail and captured output; --follow streams it, --diagnostics selects failed-stage evidence, and --range START:END reads a bounded retained byte range. Monitors
sase monitor resume Launch the recorded follow-up of a terminal monitor from its frozen result without rerunning the command; -k/--checkpoint binds an authored checkpoint for a manual recovery branch and -m/--model picks the follow-up model. Monitors
sase monitor stop Stop a running monitor; no follow-up agent launches. Monitors
sase pipe PROMPT End this agent's turn and continue as the next session member; kills the caller. Monitors

A long command (just check-full, a CI wait, a deploy) should run under a monitor rather than blocking an agent turn — see the /sase_monitor skill. Handing this agent's own turn to a successor is a different, in-process hand-off — see the /sase_handoff skill.

Prompt And Workflow Authoring

Command Purpose Details
sase macro expand Expand macro references in prompt text, with optional trace output. Macro reference syntax
sase macro explain Dry-run a workflow and show the execution plan. Workflows
sase macro list Emit the structured macro catalog as JSON. Macro catalog
sase macro graph Generate a workflow DAG as Mermaid or text. Workflow graphing
sase macro catalog Render visible macros to a formatted PDF catalog. Macro catalog
sase macro show Show one macro definition with properties, provenance, and syntax highlighting. Macro show
sase macro types List macro input types, including plugin-shared enums, or show one type detail. Macro input types
sase lsp Start the macro language server over stdio. Editor integration
sase editor helper-bridge JSON helper operations for editor integrations. Editor helper bridge
sase file list Emit JSON filesystem completion candidates. Editor completion commands
sase file-history list Emit recently referenced files for editor completion. Editor completion commands
sase file-history delete Remove one path from the file-reference history. Editor completion commands
sase skill / sase skill list Inspect generated skill sources, provider targets, and deployed-file drift. Initialization, bundled skills
sase skill init Generate and deploy agent skill files from macro source templates. Initialization, bundled skills
sase skill log Summarize or inspect audited generated skill-use events. Skill field
sase skill use Agent-side audit event recording that a generated skill was used. Skill field
sase init skills Compatibility alias for sase skill init. Initialization
sase snippet add Add a writable ace.snippets entry; refuses overwrite/shadow unless -F. Snippet CLI
sase snippet delete Delete a writable snippet and print the restore command plus any revealed source. Snippet CLI
sase snippet / sase snippet list List effective snippets for a project, filtered by an optional substring. Snippet CLI
sase snippet show Show one snippet's raw/composed definition, source stack, aliases, and links. Snippet CLI

Use #name(...) for inline macro expansion and #!workflow(...) for standalone workflow references. Workspace references such as +<project> (project tag), #git:<project>, and plugin-provided references are resolved before the prompt or workflow runs.

Review And Delivery

Command Purpose Details
sase final / sase final list List effective host-owned finalizer instances; the bare group defaults to this view. Commit finalizer
sase final show / doctor Inspect one finalizer instance or diagnose effective provider configuration. Configuration
sase final context Publish and print the current turn's selected finalizers and declaration obligations. Commit finalizer
sase final submit Validate and save one finalizer declaration for host execution after the model turn. Commit finalizer
sase final defer Submit one rare typed repository deferral for host adjudication. Configuration
sase final prepare Seal a single-use declaration and exact verification command for conditional no-model host completion. Prepared completion
sase final status Project one agent turn's finalizer run view (pretty or -f json); the same view the Agents tab ⊛ FINAL deck renders. Defaults to the calling turn inside a SASE turn; -d/--artifacts-dir reads artifacts directly. Finalizers on the Agents tab
sase stitch create Dispatch a commit, proposal, or PR through the configured VCS provider; a commit with an assigned bead needs -B/--bead-action keep or close. Commit workflows
sase revert Revert a Patch by pruning its change and archiving its diff. Commit workflows
sase restore Attempt to restore a reverted Patch from its archived diff; the current final commit-recreation command is invalid if that step is reached. VCS restore
sase comments Preview mentor comments from JSON with syntax-highlighted code context. Mentors

Delivery commands delegate to the VCS and workspace provider layers, so the same command surface can support plain git, GitHub pull requests, and other provider plugins.

Operations And Diagnostics

Command Purpose Details
sase doctor Run read-only install, config, provider, project, and state diagnostics for support. -F previews and applies the opt-in ProjectSpec duplicate-block repair after confirmation. -R restores stranded link-index deletions in primary-nested sidecar clones rather than committing them. Doctor support reports
sase config layers Show the configuration merge chain. Configuration
sase config init Write or refresh owner identity in the user config. Initialization
sase init config Compatibility alias for sase config init. Initialization
sase config show Dump the final merged configuration, optionally filtered by key. Configuration
sase config mentor-match Trace mentor profile matching for a Patch. Mentors
sase config migrate-keymap-actions Rewrite, in place in every loaded config layer, ace.keymaps.app overrides that still use a retired action name to the canonical action; sase doctor -C config.keymap_actions reports them. Keymaps
sase usage / usage list Inspect cached provider subscription capacity without probing providers; JSON, plain, verbose, and repeatable provider filters are available. Subscription usage
sase usage refresh Submit or join bounded durable usage probes; foreground mode waits and renders the refreshed cache, while --background returns the submission receipt. Configuration CLI flags
sase flag / flag list Inspect registered feature flags, resolved values, provenance, saved vs effective state, flag task beads, and removal countdowns. flag new <key> scaffolds a flag and its typed removal bead; it requires --when-enabled, --when-disabled, and --remove-when. Configuration, Beads
sase flag enable / flag disable Persistently enable or disable a registered flag in $SASE_HOME/feature_flags.json (not portable config). -j/--json emits one mutation plus restart envelope. Restarts the running scheduler service proc, leaves a stopped scheduler stopped, and tells you to restart any separately running sase's TUI. Unknown flags exit 2; restart failure exits 1 without rolling back the save. Configuration
sase file-hook / file-hook list List effective post-commit/artifact file hooks, filters (including producers), commands, and contributing config layers. history and show inspect producer audits for unmatched, dispatched, or failed events. File hooks
sase core health Check that the required sase_core_rs extension is loadable and working. Rust backend
sase migrate / migrate list Temporary offline kit for the canonical-only local-state cutover: list, backup, plan, run, resume, status, verify, and restore. Never runs automatically. --apply gates changes to source or live roots, but planning records control files and a restore without --apply still creates a staging copy. Local state cutover
sase validate Run the portable validation bundle: required plugins, memory/repo/skills initialization checks, file-hook config, SDD plan links, and the agents-sidecar prompt archive. Configuration CLI flags
sase telemetry cleanup-test-data Preview or remove telemetry rows carrying known exact test labels; deletion requires -y. Telemetry
sase telemetry health Run subsystem health assessment. Telemetry
sase telemetry list Display the debugging and health metric catalog. Telemetry
sase telemetry snapshot Query current metric values from the local store. Telemetry
sase telemetry status Show local telemetry store and flusher status. Telemetry
sase version Show the local sase, sase-core-rs, and installed plugin package inventory for this runtime. Runtime inventory
sase plugin / plugin list Browse the plugin catalog, marking built-in, community, installed, latest, and ↑ update indicators. Plugin catalog
sase plugin show Show one plugin's detail panel: install status, latest version, repository, topics, and metadata. Plugin catalog
sase plugin install Install a plugin into sase's own uv tool environment, resolving the name through the catalog. Installing and updating plugins
sase plugin update Upgrade one installed plugin (or every plugin with -a), leaving sase core pinned. Installing and updating plugins
sase plugin uninstall Remove one installed plugin from sase's own uv tool environment, preserving core and other plugins. Removing a plugin
sase <plugin-command> Run a plugin-mounted top-level command (for example sase listen), routed to the plugin with the untouched argv after the command word. Command plugins
sase update Upgrade sase and all installed plugins together; registry packages via uv tool upgrade, editable/dev installs via git fast-forward. -n previews, -j emits JSON, -q prints only a summary, -v streams full step output, and -t/--to dev\|pypi switches the install mode after confirmation (-y skips it). Updating sase and plugins
sase completion / completion list Show shell-completion generator availability, install status, target path, .zwc freshness, and stamp version. Shell Completion
sase completion install [SHELL] Detect the shell, write the script, zcompile it (zsh), verify registration, and stamp the install; -d previews, -f overwrites a foreign file. Shell Completion
sase completion refresh [SHELL] Regenerate every stamped local install, or one named shell, at its existing target; -d reports drift without writing and -j emits per-shell outcomes. Refresh existing installs
sase completion deploy-chezmoi Render all three portable completion loaders into the chezmoi source tree, remove legacy generated stamp sources, then commit, push, and apply; -d previews and -c/-n/-a stop before commit, push, or apply. Shell Completion
sase completion zsh / bash / fish Print a completion script for one shell to stdout or -o/--output FILE. Shell Completion
sase completion spec Print the structural completion spec as JSON. Shell Completion
sase completion candidates KIND Print live value<TAB>description candidates for one value kind, filtered by an optional prefix; the primary entry point is the generated scripts' own dynamic-value calls, not direct use. Shell Completion
sase logs Collect and package agent run logs for a date range. Configuration CLI flags
sase revive-log Inspect the agent-revival audit log (start / success / failure events). Agent revival audit log
sase artifact / artifact list List indexed artifacts with kind, project, agent, --since, --unused, and query filters; bare sase artifact defaults to list. Aliased as sase artifact-file. sase's TUI browses the same index under Artifacts → Files. File pane · Configuration CLI flags
sase artifact create Copy an explicit file into persistent agent artifact storage and print its durable file: ref; agent-only (SASE_AGENT=1). Agent attachments
sase artifact doctor Report artifact-index and link-graph health, including VCS provenance, dangling refs, projections, read outbox, and derivation coverage; -f repairs/backfills and -v verifies stored and VCS-backed bytes. Artifact Links · VCS-backed artifact files
sase artifact link / link list Add, list, inspect, suggest, migrate, and remove typed artifact links. link relation explains the closed registry; link suggest returns write-free hard-evidence candidates. Artifact Links
sase artifact link import-indexes Preview the one-time legacy links/ cutover; --apply <attestation> publishes the deterministic baseline event and resumable sidecar markers. Legacy index cutover
sase artifact open Resolve any artifact reference, including generated bead and agent pages, and open it with the viewer matching its kind and mime type. Configuration CLI flags
sase artifact path Print the single absolute filesystem path a reference resolves to, materializing VCS-backed rows on demand. Configuration CLI flags
sase artifact prune Plan retention with durable-reference and consumption protection; --apply moves selected automatic rows into restorable trash and refuses if a required protection source is unavailable. Store lifecycle
sase artifact prune-runs Preview removal of old per-run ace-run artifact directories and empty out-of-range shards; --apply currently refuses and exits 1 because ACE-run deletion is preview-only. Artifact retention
sase artifact read Print one artifact as context after recording an audited reason; inside a SASE agent run with identity it also writes a read edge from the agent to the artifact. Artifact Links
sase artifact reclaim Plan conversion of stored automatic rows to verified VCS-backed identities; consumed and durably referenced rows stay protected, and mutation requires --apply. Store lifecycle
sase artifact show Show one artifact reference's metadata, resolution report, and consumption summary, or a JSON envelope with -j. Configuration CLI flags
sase artifact pane show Explain one Artifacts pane contract: every capability ON or OFF with the named rule, declared fact, and reason. -j prints the JSON payload. Artifacts pane contract
sase artifact stats Report artifact-store economics, protection-source counts and availability, trash occupancy, and the default retention plan. Store lifecycle
sase artifact trash List, permanently purge, or restore entries in the restorable artifact trash. Configuration CLI flags
sase agent prompts Browse and validate the canonical agents-sidecar prompt archive. show prints the archived Markdown document, and migrate --write moves historical plans-sidecar prompts into prompts/<YYYYMM>/. Agent Hood Synchronization
sase agent-cli / agent-cli list Inventory supported coding-agent CLIs with versions, install methods, and update markers. Agent providers
sase agent-cli update Update selected agent CLIs (or every safe candidate with -a); -n previews commands and skips. Agent providers
sase agent-cli install Install agent CLIs from the install script or npm package their provider declares, after showing the script URL, SHA-256 digest, command, and target (or the exact npm install -g command and global bin directory); needs -y or an interactive confirmation, and -n previews without executing. Agent providers
sase var / sase var list Discover unique output-variable keys and distinct typed values across indexed agent history. Macro variables
sase var get Show the current or quoted <agent_name> snapshot, or retrieve precise values with exact, global, hood, key-wildcard, and JSON-path selectors. Macro variables
sase var set Attach named string or structured JSON output variables from assignments, literal text, files, or stdin. Macro variables
sase path Print well-known paths such as schemas and macro directories. Configuration CLI flags
sase repo list Show primary, sidecar, linked, and opened external repos; use --all or --json for cross-project and clone-matrix views. Configuration CLI flags
sase repo log Summarize the durable repository-open audit log, with repo, agent, workspace, event-ID, and JSON filters. Configuration CLI flags
sase repo open Open an inventory repo, another SASE project, or provider ref in the inferred workspace; GitHub refs reuse a matching configured repo before external materialization. Configuration CLI flags
sase tool / tool list List the current project's named tools with LAST result and observed TYPICAL duration; bare sase tool defaults to list, and -j emits versioned JSON. Configuration CLI flags
sase tool run Execute a named tool or an ad-hoc -- ARGV... command, record a ToolRun, and return the child's exit code. Configuration CLI flags
sase tool runs List recorded ToolRuns for the current project (or -a for every project). Configuration CLI flags
sase tool show Show one ToolRun by exact id, including evidence completeness, repository/input mutation, toolchain probes, stage timing, unattributed time, and host samples; -j emits JSON and -l replays retained stdout/stderr. Configuration CLI flags
sase tool wait Block until one ToolRun settles or the -t deadline passes, then exit with its exit code (124 when still running); the run is never affected. Named Tools and ToolRuns
sase tool stop Record a durable stop request for one ToolRun and stop it through its owner (proc, monitor, or inline wrapper); reports stop requested separately from stopped. Named Tools and ToolRuns
sase tool failures List grouped failure signatures from stored triage for the current project over the last 7 days (-a for every project). Named Tools and ToolRuns
sase tool receipt Report the covering verdict receipt for one named tool at the current fingerprint, or a typed refusal; -a/--accept {pass,no-new}, -j emits versioned JSON. Exits 0 covered, 1 refused, 2 usage. Named Tools and ToolRuns
sase tool receipts List retained receipts and content-equivalent repeat opportunities; -d/--days N, -j emits versioned JSON. Measurement only, never changes execution. Named Tools and ToolRuns
sase tool stats Report ToolRun durations, waste, repeats, backtest, and pressure for the current project over the last 7 days (-a for every project, -t for one tool, -d 1..180); -j emits versioned JSON. Read-only and machine-local. Named Tools and ToolRuns
sase disk / disk list Attribute SASE disk usage by owner, section, coverage, horizon, and path; bare sase disk defaults to list, and -j emits JSON. Configuration CLI flags
sase disk reap Preview owner cleanup passes, or run them with --apply; exits 1 when any owner step is blocked or fails. Unowned Cargo-shaped strays are reported but never deleted by this command. Configuration CLI flags
sase workspace list List one project's registry or use --all for the cross-project workspace inventory. Workspace provider
sase workspace path Print the checkout path for a workspace number. Workspace provider
sase workspace cleanup Remove stale unclaimed managed checkouts older than the configured TTL. Workspace provider
sase workspace compact Retrofit safe managed checkouts to share primary Git objects and repack away duplicate private object packs. Workspace provider
sase workspace repair Reconcile the workspace registry, missing checkouts, and SASE-managed Git object alternates. Workspace provider
sase workspace migrate Opt-in move of adjacent checkouts to a managed root, with optional symlink transition and finalization. Workspace provider
sase mobile gateway start Start the workstation-hosted mobile gateway. Mobile gateway
sase mobile agent-bridge Fixed JSON bridge used by the mobile gateway for agent operations. Mobile gateway
sase mobile helper-bridge Fixed JSON bridge used by the mobile gateway for workflow helper operations. Mobile gateway
sase mobile notification-bridge Fixed JSON bridge used by the mobile gateway to execute gate and question actions. Mobile gateway

The sase artifact show, read, path, open, and link commands take logical references without a leading @, for example sase artifact show file:default:<digest>. Add the sigil when embedding the same reference in a launch prompt: sase run "review @file:default:<digest>". This bare-CLI/@-in-prompts rule also applies to document roles, chats, beads, agents, commits, and bugs. path accepts only references with a filesystem identity; open can also open a bug in a browser but rejects commits.

stats, prune, reclaim, and trash are the store's lifecycle commands, and they are deliberately staged: stats only reports, prune and reclaim print a plan and change nothing unless --apply is passed, and every removal either of them makes moves the stored bytes and the complete index row into a restorable trash under ~/.sase/artifacts/trash/. sase artifact trash restore puts an entry back; only sase artifact trash purge deletes permanently, and without -a/--all it purges only entries older than artifacts.retention.trash_grace_days. Trashed bytes still occupy disk until that purge runs. Explicit artifacts, artifacts a ProjectSpec, plan, bead, or research document references, artifacts recorded in the consumption ledger, and the newest capture of every label are never selected; if a required protection source cannot be read, --apply refuses rather than under-protecting. See Store Lifecycle.

sase artifact list inventories only the persistent artifact-file index; it is not a catalog of every reference kind and it does not browse the agents-sidecar prompt archive. Use sase agent prompts list/show/validate for archived prompts and their published ARTIFACTS links. Use sase's TUI grouped @ completion to browse prompt references, or its contextual Copy as… palette to copy a reference or pre-fill a new agent prompt from the selected entry. See Getting Started for the handoff workflow and prompt preprocessing for launch-time resolution.

Operational commands are intentionally narrow. Helper bridges expose fixed JSON operations for editor and mobile clients; they are not general shell or filesystem APIs.

sase --full-help also lists durable-operation entrypoints that sase's TUI submits as durable procs rather than commands meant for everyday typing: Patch lifecycle actions (sase patch accept, archive, mail, rebase, restore, revert, rewind, reword, status, submit, sync, and tag), sase agent revert, sase agent persist-cleanup, sase agent persist-directive, sase bead apply-status, and sase notify apply-state / apply-state-many. They take -Q/--request-path and -R/--result-path for the private request and typed result sidecars, defaulting to $SASE_PROC_REQUEST_PATH and $SASE_PROC_RESULT_PATH. Several everyday commands, such as sase run, sase agent drain, sase gate act, sase launch approve, and sase plugin install, accept the same two options so the TUI can run them as procs.

Doctor Support Reports

sase doctor is the first command to run when SASE behaves unexpectedly. It is read-only by default (apart from the agent-hold reconciliation described below): it does not launch agents, call LLM APIs, repair state, run tests, or scan full artifact history. The human output is grouped by subsystem and puts next-step commands beside warnings and errors.

Common forms:

sase doctor                 # compact human report
sase doctor -v              # include every check plus bounded details
sase doctor -j              # stable JSON report for scripts or support bundles
sase doctor -D              # add slower read-only deep checks
sase doctor -C runtime      # run one group
sase doctor -C llm.default  # run one check
sase doctor -C project.junk_directories -C workspace.missing_checkouts
sase doctor -F              # preview and confirm ProjectSpec duplicate-block repair
sase doctor -R              # preview and confirm restore of stranded primary sidecar link-index deletions

Exit codes are designed for support-first use. OK, WARN, and all-skipped reports exit 0; ERROR exits 1. Use sase doctor -s / --strict when automation should treat warnings as failures.

The JSON report uses schema_version: 1 and stable top-level fields such as status, counts, selected_checks, and checks. Individual check data payloads stay bounded and may gain additional keys over time, so scripts should key off check ids and statuses rather than assuming every nested field is permanent.

The completion group is advisory and never fails a report: completion.install reads the shell-completion install stamps, and the deep-only completion.registration spawns a real shell to confirm the script is actually registered (sase doctor -D -C completion.registration). Selecting a deep check without -D is rejected rather than silently skipped.

project.junk_directories reports directories under ~/.sase/projects/ that have no canonical ProjectSpec and gives a manual-review cleanup hint. project.duplicate_patch_blocks reports duplicate raw Patch blocks in active and archive ProjectSpec files. sase doctor -F / --fix-duplicate-blocks previews that repair and, after confirmation or -y / --yes, keeps the newest block per Patch name without changing the default read-only doctor behavior. project.primary_sidecar_link_dirt flags uncommitted links/ dirt in sidecar clones nested under a project's primary checkout, which blocks pull-based sidecar auto-sync. sase doctor -R / --fix-primary-sidecar-links restores stranded canonical link-index deletions (git restore) as a user-origin action; it does not commit them, because durable deletions must land via the machine write lane and reach the primary through auto-sync. workspace.missing_checkouts scans enabled and disabled projects through the shared inventory, lists registered checkout paths missing from disk, and suggests a per-project sase workspace repair -n preview. workspace.occupancy_conflicts reads every project's RUNNING field and each checkout's occupant record, then reports duplicate workspace-number claims, a live claim whose occupant names a different live pid, and occupant records with no matching claim. Conflicts include the last workspace-claim ledger mutation and caller tag when one exists; the check never auto-repairs. config.macro_directives locates macro and workflow definition files that still use retired directive syntax, such as a %wait(priority=...) that has moved to %queue. agent_holds.stale warns about agent holds whose armer has died or whose TTL has passed; like sase agent hold list, it reconciles the hold store as it reads it, so the stale records it reports are also pruned. Apart from that reconciliation, default doctor checks do not mutate state.

When asking for help, attach sase doctor -v for a readable report or sase doctor -j for a machine-readable report.