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.

For exhaustive flag tables, see the configuration reference.

Daily Operation

Command	Purpose	Details
sase ace	Open ACE, the interactive control surface for ChangeSpecs, live agents, notifications, and axe state.	ACE TUI
sase run [PROMPT]	Launch an agent or workflow from a prompt, an xprompt reference, a workflow reference, history, or an editor buffer.	XPrompts, workflows
sase agent list	List active and recent agents across projects.	ACE Agents tab
sase agent show	Render one agent's detail panel by name.	Agent attachments
sase agent kill	Terminate a running agent.	ACE TUI
sase agent tag	Set, clear, or list user-defined agent tags used for grouping.	ACE TUI
sase agent archive	Maintain dismissed-agent bundle summary indexes (rebuild-index, verify).	ACE 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).	ACE TUI
sase agent names migrate-auto	Backfill the permanent agent-name registry from legacy auto-generated names; pass --force to rerun.	ACE TUI
sase chat list	List recent chat transcripts.	XPrompts
sase chat show	Show one chat transcript by agent name, path, or basename.	XPrompts
sase prompt list	List, search, and filter previously submitted prompts (pretty table or JSON).	Prompt history
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 xprompt, or export it to a file or SDD snapshot.	Prompt history, XPrompts
sase prompt prune	Curate the prompt-history store with delete, prune, and read-only doctor/stats.	Prompt history
sase notify	Shortcut for sase notify list.	Notifications
sase notify create	Create a notification from JSON input.	Notifications
sase notify list	List recent notifications, optionally filtered by sender, tag, unread state, or query.	Notifications
sase notify show	Show one notification as Markdown or JSON.	Notifications
sase repro replay	Replay an Agents-tab reproduction bundle through the headless TUI harness and emit a verdict.	ACE TUI
sase repro capture agents-tab	Capture a commit-safe out-of-band Agents-tab bundle from current filesystem state.	ACE TUI

sase run can run in the foreground, launch detached background agents with --daemon, resume previous conversations, or expand multi-prompt input into sequential background launches. ACE uses the same launch machinery when users start agents from the TUI.

Command groups with an exact list child default to that list view when invoked bare, including sase amd, sase bead, sase chat, sase file, sase file-history, sase memory, sase notify, sase plugin, sase project, sase prompt, sase sdd, sase skill, sase telemetry, sase workspace, and sase xprompt. Nested groups such as sase agent tag, sase axe chop, and sase axe lumberjack follow the same rule.

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 memory list -j, or sase workspace list --json.

Work Tracking And Planning

Command	Purpose	Details
sase changespec current	Render the ChangeSpec associated with the current workspace.	ChangeSpecs
sase changespec migrate-extension	Rename legacy .gp ProjectSpec files to the canonical .sase extension.	ProjectSpec
sase changespec search	Search and filter ChangeSpecs with the query language.	Query language
sase changespec sync-deltas	Recompute the DELTAS field for a ChangeSpec from VCS state.	ChangeSpecs
sase init	Check and initialize AMD, memory, SDD, and skills from one coordinator.	Initialization
sase amd / sase amd list	Inventory project, home, and chezmoi AGENTS.md files plus nearby provider shims.	Initialization
sase amd init	Create or refresh AGENTS.md files and provider shims for the selected AMD root or roots.	Initialization
sase init amd	Alias for sase amd init.	Initialization
sase memory / sase memory list	Show loaded, referenced, available, and missing memory files.	Memory
sase memory read	Agent-side read of one long-term memory file with an attributable audit event.	Memory
sase memory write	Agent-side proposal for human-reviewed long-term memory; --notify can add an inbox item.	Memory
sase memory review	Human listing, inspection, approval, editing, or rejection of pending memory proposals.	Memory
sase memory log	Summarize audited memory reads; --include proposals also shows proposal and review events.	Memory
sase memory init	Create or refresh project/home memory files and AGENTS memory references.	Initialization
sase init memory	Alias for sase memory init.	Initialization
sase sdd init	Enable version-controlled SDD and refresh generated guide files.	SDD
sase init sdd	Alias for sase sdd init.	SDD
sase sdd list	List SDD prompt, tale, epic, legend, or all Markdown artifacts.	SDD
sase sdd links	Inspect prompt/artifact frontmatter links.	SDD
sase sdd validate	Validate SDD frontmatter links.	SDD
sase sdd repair-links	Infer and optionally write missing bidirectional SDD 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, legend, or phase issues.	Beads
sase bead list	List bead issues by status, type, or tier.	Beads
sase bead search	Search bead IDs, titles, notes, plan paths, metadata, and lifecycle fields.	Beads
sase bead ready	Show open issues whose dependencies are closed.	Beads
sase bead blocked	Show issues blocked by open dependencies.	Beads
sase bead show	Show one issue.	Beads
sase bead update / open / close / rm	Mutate issue metadata or lifecycle state.	Beads
sase bead dep add	Add an issue dependency.	Beads
sase bead sync	Export the bead database to git-tracked JSONL and stage it.	Beads
sase bead stats / doctor	Inspect project statistics or bead-store health.	Beads
sase bead work	Launch phase agents for an epic, or epic-planning agents for a legend.	Beads
sase project list	List active projects by default, or include hidden lifecycle states with --state.	Project lifecycle
sase project show	Show lifecycle, workspace, launchability, and warning details for one project.	Project lifecycle
sase project set-state / aliases	Update PROJECT_STATE under the ProjectSpec lock.	Project lifecycle
sase project alias	List, add, remove, or clear PROJECT_ALIASES under the ProjectSpec lock.	Project aliases
sase plan / sase plan list	Show the plan pipeline dashboard: pending proposals, recent approvals, and inferred rejects.	XPrompt directives
sase plan approve	Approve one pending plan by ID or prefix; --kind chooses approve/commit/epic/legend/tale.	XPrompt directives
sase plan propose	Submit a plan file for approval from the plan skill path.	XPrompt directives
sase plan search	Search repo-local SDD plans and the machine-local plan archive by literal text and metadata.	SDD
sase questions	Ask structured user questions from the questions skill path.	XPrompt directives

ChangeSpecs are CL/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.

sase project defaults to sase project list, and sase project list defaults to active projects. Use sase project list --state all --json to inspect inactive and sibling projects, sase project deactivate <project> to hide a dormant project from default launch views, and sase project activate <project> to make a hidden project launchable again. Deactivating refuses projects with live RUNNING claims or active artifact markers unless --force is passed. Deprecated archive and close aliases still set inactive for compatibility. ACE's ,p Project Management panel 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 ACE's ,p panel 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. The ACE ,p Project Management panel 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 project name. Providers may also generate aliases automatically; for example, the GitHub provider can create foo and then foo-2 aliases for distinct owner/foo repositories while keeping stable canonical project records. Use the same sase project alias commands to inspect or adjust those generated aliases.

Active-only project discovery is also the default for launch pickers, ChangeSpec searches, project-local xprompt catalogs, broad mobile helper catalogs, and all-known bead helper reads. Sibling records are hidden from those surfaces and are intended for configured linked repositories. To open one, pass its linked-repo name as the workspace CLI's project override: sase workspace open -p <linked_repo> -r "<reason>" <workspace_num>. Agent-history views that need older artifacts opt into all project states explicitly.

sase plan defaults to sase plan list. The dashboard has Proposed, Approved, and Rejected sections. Proposed rows include an id_prefix, agent, project, provider/model, plan path, and response directory; pass that prefix to sase plan approve <prefix>. If the selector is omitted, exactly one pending proposal must exist. 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 and legend commit the matching SDD tier and launch 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.

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

Automation

Command	Purpose	Details
sase axe start	Start the axe orchestrator and its lumberjacks.	Axe
sase axe stop	Stop the running orchestrator.	Axe
sase axe chop list	List configured chop jobs.	Axe chops
sase axe chop run <name>	Run one chop in the foreground.	Axe chops
sase axe lumberjack list	List configured lumberjacks.	Axe lumberjacks
sase axe lumberjack run <name>	Run one lumberjack in the foreground for debugging.	Axe lumberjacks
sase axe lumberjack status	Show lumberjack process status.	Axe
sase axe maintenance enter	Pause scheduled lumberjack ticks with a recorded reason.	Maintenance mode
sase axe maintenance exit	Resume scheduled lumberjack ticks.	Maintenance mode
sase axe maintenance status	Inspect the maintenance marker.	Maintenance mode

Axe runs scheduled hooks, mentors, comment polling, workflow checks, %wait dependency resolution, cleanup, and error digests. ACE starts axe automatically unless launched with sase ace --no-axe.

Prompt And Workflow Authoring

Command	Purpose	Details
sase xprompt expand	Expand xprompt references in prompt text, with optional trace output.	XPrompt reference syntax
sase xprompt explain	Dry-run a workflow and show the execution plan.	Workflows
sase xprompt list	Emit the structured xprompt catalog as JSON.	XPrompt catalog
sase xprompt graph	Generate a workflow DAG as Mermaid or text.	Workflow graphing
sase xprompt catalog	Render visible xprompts to a formatted PDF catalog.	XPrompt catalog
sase lsp	Start the xprompt 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 xprompt 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

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

Review And Delivery

Command	Purpose	Details
sase commit	Dispatch a commit, proposal, or PR through the configured VCS provider.	Commit workflows
sase revert	Revert a ChangeSpec by pruning its change and archiving its diff.	Commit workflows
sase restore	Restore a reverted ChangeSpec by reapplying its archived diff.	Commit workflows
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.	Doctor support reports
sase config layers	Show the configuration merge chain.	Configuration
sase config show	Dump the final merged configuration, optionally filtered by key.	Configuration
sase config mentor-match	Trace mentor profile matching for a ChangeSpec.	Mentors
sase core health	Check that the required sase_core_rs extension is loadable and working.	Rust backend
sase validate	Run SASE validation checks: initialization drift plus SDD frontmatter validation.	Initialization, SDD
sase telemetry status	Show telemetry configuration and reachability.	Telemetry
sase telemetry list	Display the metric catalog.	Telemetry
sase telemetry snapshot	Fetch current metric values.	Telemetry
sase telemetry dashboard	Open the live telemetry dashboard.	Telemetry
sase telemetry health	Run subsystem health assessment.	Telemetry
sase telemetry export-config	Export the bundled monitoring stack.	Telemetry
sase version	Show the local sase, sase-core-rs, and installed plugin package inventory for this runtime.	Runtime inventory
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 create	Move an explicit file into persistent agent artifact storage.	Agent attachments
sase var set	Attach named output variables for ACE metadata and waited-agent Jinja rendering.	XPrompt variables
sase plugin / list	Inventory installed SASE plugin entry points and configured/available chop scripts.	Plugins
sase plugin doctor	Diagnose plugin resource loading, configured chops, and optional integration prerequisites.	Plugins
sase path	Print well-known paths such as schemas and xprompt directories.	Configuration CLI flags
sase workspace list	List managed workspace checkouts in the registry, including primary #0.	Workspace provider
sase workspace path	Print the checkout path for a workspace number.	Workspace provider
sase workspace open	Materialize, prepare, and print a workspace path.	Workspace provider
sase workspace cleanup	Remove stale unclaimed managed checkouts older than the configured TTL.	Workspace provider
sase workspace repair	Reconcile the workspace registry with the filesystem.	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

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

Doctor Support Reports

sase doctor is the first command to run when SASE behaves unexpectedly. It is read-only by default: 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

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.

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