Skip to content

Macro CLI and editor support

This page documents the macro CLI subcommands and editor language server.

CLI

Usage, options, and arguments for every sase macro command are in the generated macro CLI reference.

sase macro list returns JSON catalog entries for visible macros and workflows. Each entry includes insertion, the authoritative reference text for clients, plus type, kind, source, input definitions, tags, skill status, and a content preview. Standalone workflows insert as #!name; macros and embeddable workflows insert as #name. Step inputs are supplied by workflow execution and do not appear in the user input list.

For macro argument and input semantics, see Arguments and typed inputs.

Editor LSP

sase lsp starts the SASE macro language server over stdio for editor integrations. It resolves the server command in this order:

  1. SASE_MACRO_LSP_CMD, parsed as a shell-style command for development.
  2. A sase-macro-lsp binary in the current Python environment's bin/ directory.
  3. sase-macro-lsp on PATH.
  4. The newer debug or release sase-macro-lsp binary under a sibling ../sase-core checkout.
  5. cargo run --manifest-path ../sase-core/Cargo.toml -p sase_macro_lsp -- when cargo is available and the sibling checkout has a Cargo.toml.

Examples:

sase lsp
sase lsp --version
SASE_MACRO_LSP_CMD='cargo run --manifest-path ../sase-core/Cargo.toml -p sase_macro_lsp --' sase lsp

Use SASE_MACRO_LSP_CMD for any non-default LSP command, including a custom binary that should beat the managed venv copy. Full editable-install SASE updates reinstall the server into the uv-tool venv when pulled sase-core commits change. SASE_CORE_DIR is a Justfile build/install override, not part of sase lsp command resolution.

The LSP loads the supported macro catalog sources directly in Rust for completion, hover, diagnostics, and definition requests. sase lsp exports the installed package macro paths to the server so built-in Markdown prompts, YAML workflows, default config prompts, project-local prompts, user config prompts, and memory prompts do not require a Python helper subprocess on the completion path. The Python helper bridge remains stable for mobile clients and as a compatibility fallback for sources the Rust loader cannot discover.

When the editor advertises LSP completionItem.snippetSupport, the server also returns SASE snippets as ordinary CompletionItemKind.Snippet entries after bare trigger words such as fix or review. Snippet entries are loaded from the same registry as sase's TUI: macros with snippet front matter plus user-defined ace.snippets, with ace.snippets winning on trigger collisions. The registry also includes the generated initial-capital aliases (foo → Foo), so a completion for Foo appears wherever foo does. The editor does not need to shell out or parse SASE config to discover snippets.

The Python helper operation sase editor helper-bridge snippet-catalog is the authoritative snippet registry because it matches sase's TUI macro composition behavior. The Rust server also has a native fallback for simple macro snippets and ace.snippets so completion can degrade gracefully if the helper is unavailable. That fallback intentionally skips macros that require complex Jinja or composition it cannot mirror exactly; when the helper is available, its response is preferred.

The LSP also consumes the project's glossary memory web, authored as strand files under sase/memory/glossary/; see Memory Webs. A leading VCS workflow reference selects the glossary project for the document, otherwise the active workspace project is used. Glossary phrases are emitted as standard type semantic tokens, with the same case-insensitive, code-literal-skipping, longest-match scanner sase's TUI uses. A phrase wrapped across one line break is emitted as one semantic token per line. Derived plurals of terms and aliases are matched like configured aliases. sase-nvim underlines those tokens by default through an overridable SaseGlossaryTerm highlight group. Hover returns Markdown for the canonical term, aliases, project, and source context, and go-to-definition targets the glossary strand file's definition range. Explicit macro and artifact references keep precedence over glossary matches. When the selected project is disabled, unknown, home, unreadable, or has an invalid glossary, the server suppresses glossary semantics for that context instead of falling back to another project's terms.

See the editor integration guide for setup, feature coverage, helper bridge usage, and troubleshooting.

sase macro

With no subcommand, sase macro defaults to sase macro list.

sase macro list

No flags. Outputs a JSON array of all available macros with name, type, source, inputs, tags, is_skill, and preview. Clients that insert references should prefer kind/insertion metadata when present so standalone workflows are inserted as #!name and inline-capable entries, including markdown macro swarms, are inserted as #name. Slash skill completion clients should filter to entries where is_skill is true.

sase macro types

Moved to sase macro.

Moved to Macro CLI and editor support.

Command behavior

With no NAME, prints grouped tables of scalar, builtin, and plugin types. With NAME, shows one type's detail card. Unknown names exit 1.

Prompt And Workflow Authoring

Flag and option details live in the generated CLI command groups:

Workflows: Macros, Workflows, Editor integration.

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.

_[project]: A sase project is a named unit of work registered with SASE. _[workspace]: A sase workspace is a numbered clone of a project's primary repo, managed by the workspace store and tracked in that project's registry.json. _[agent]: A sase agent is an agent session or a single agent that does not belong to a session. _[prompt]: A prompt is the text SASE hands to a provider to start an agent turn. _[macro]: A macro is a reusable prompt triggered with #name in agent prompts. _[Patch]: A Patch is SASE's local unit of change. _[bead]: A bead is one tracked work item in SASE's git-native issue tracker. _[plan]: A plan is a persisted, approved artifact recording the intent behind agent work. _[TUI]: The TUI is SASE's terminal interface for running agents and reviewing results. _[epic]: An epic is an executable multi-phase plan run with sase bead work. _[gate]: A sase gate is a durable, command-backed request for one user decision, created when work must pause for the user. _[monitor]: A sase monitor is a monitor turn that runs one long command under a detached supervisor, so the command outlives the agent that started it. *[stitch]: A stitch is the lightweight ordered change record inside a Patch's STITCHES: section.