shared-agents CLI (sa)

Canonical live help: run sa or sa help — prefer that over memorizing flags.

sa                  # help overview (default)
sa help             # same
shared-agents …     # alias
sharedagents …      # alias

Without shell aliases (agents, CI, fresh shell):

"${SHARED_AGENTS_HOME:-$HOME/.shared-agents}/scripts/sa" help

Repo root (dev checkout): ./sa · ./sa install

Env: SHARED_AGENTS_HOME (default ~/.shared-agents) · Version: sa version

First-time setup

Recommended (Core + private team repo + adapters):

curl -fsSL https://raw.githubusercontent.com/netgrade-digital/shared-agents/refs/heads/main/scripts/bootstrap.sh | bash
# Piped curl uses /dev/tty for the wizard when possible (TUI or text prompts).
# Force auto-install only: SA_BOOTSTRAP_NON_INTERACTIVE=1 curl … | bash
# or after clone: ./scripts/bootstrap.sh  ·  sa bootstrap
source ~/.bashrc   # fish: source ~/.config/fish/config.fish
sa check
sa team verify    # optional but useful after bootstrap

Classic (Core only, then wizard — team repo optional in wizard):

git clone git@bitbucket.org:netgrade/shared-agents.git ~/.shared-agents
cd ~/.shared-agents
./sa install
source ~/.bashrc   # fish: source ~/.config/fish/config.fish

From dev checkout without ~/.shared-agents yet: ./sa install — wizard runs before clone; cancel leaves no ~/.shared-agents.

New AI tool installed? → run sa install again.

Commands (overview)

Alias: sa install = sa setup

Status — sa status

Shows easy-to-forget work:

sa status              # full list (or “all clear ✓”)
sa status --brief      # one line
sa status --quiet      # print only when action needed (exit 1)
sa status --json       # CI / scripts

After sa sync (non-quiet): runs sa status --quiet for a short terminal hint.

Rule-Link(s) in brief status often means a Cursor rule exists as a regular file — sa doctor --fix backs it up and relinks.

sa check vs sa team verify: check uses quick check_team_setup() warnings; sa team verify is stricter (folders, index, origin, --strict).

Doctor — sa doctor

sa doctor              # diagnose (same sources as sa status)
sa doctor --fix        # backup blocking rule files + run sync-links
sa doctor --fix -y     # no prompts (default yes on --fix)
sa doctor --fix --dry-run

Backups: $SHARED_AGENTS_HOME/.doctor-backups/. Does not replace learnings workflow or run full sa install.

Setup — sa install

Calls install.sh (manifest-driven, idempotent).

Wizard (recommended, TTY)

sa install

• Cursor / VS Code terminal: often plain text wizard (SA_WIZARD_PLAIN=1)
• foot / alacritty: TUI with arrow keys

Quick / CI

sa install --non-interactive
sa install --non-interactive --tools cursor,claude-code
sa install --dry-run
sa install --dry-run --wizard

Install flags (passed through to install.sh)

Low-level: ./install.sh at repo root — same options.

Check — sa check

sa check
sa check --json
sa install --check    # same

Team warnings appear under Team data: when relevant.

Sync — sa sync

sa sync
# = scripts/sync.sh pull
#   1) git pull  ~/.shared-agents        (Core — tools, adapters, OSS skills)
#   2) git pull  ~/.shared-agents/team/  (Team — learnings, team skills, team rules)
#   3) sync-links — skill symlinks, rule symlinks, team-rules AGENTS.md/CLAUDE.md blocks

• Both repos ff-only
• Without team/ / without team.remote: Core only (solo fallback under core/learnings/)
• Agents: session start via hook (session-sync.sh → sync.sh pull --quiet; links refresh quietly)
• Manual: after offline, before review, when a teammate pushed new skills/rules

Learnings workflow

Agent writes pending/  →  sa pending push  →  sa review  →  approved/

Rules (like skills — no review CLI)

Team rules: $SHARED_AGENTS_HOME/team/rules/*.mdc (flat). Core: $SHARED_AGENTS_HOME/rules/.

After edit: commit/push team repo → teammates sa sync (links skills + rules automatically).

• Cursor: symlinks → ~/.cursor/rules/ (local non-symlink files preserved)
• Zed, Pi (~/.pi/agent/AGENTS.md), Codex, Claude Code (~/.claude/CLAUDE.md), Grok Build (~/.grok/AGENTS.md), Gemini, Windsurf, …: merged <!-- shared-agents:team-rules:begin/end --> block in each tool's agents file

Optional frontmatter: targets: [zed, claude-code] — omit for all adapters.

Team skills & rules — sa skill · sa rule

Interactive wizards scaffold files in the team repo (private team/). No pending/review workflow — commit/push like any team file.

sa skill new                 # create: slug, title, description, sections
sa skill rm [name]           # remove (picker if name omitted)
sa skill list
sa skill edit [name]         # edit in $EDITOR (picker if name omitted)

sa rule new                  # create: slug, title, description, targets, body
sa rule rm [slug]            # remove (picker if slug omitted)
sa rule list
sa rule edit [slug]          # edit in $EDITOR (picker if slug omitted)

# Aliases: rm = delete = remove · list = ls

# Non-interactive (CI / scripts):
sa skill new --name my-skill --description "When user asks about …"
sa skill rm my-skill -y
sa skill edit my-skill --push
sa rule new --name my-rule --description "…" --targets cursor,zed
sa rule rm my-rule --no-git
sa rule edit my-rule --push

# Flags: --dry-run --force (new only) --no-git --push -y

Create/remove ends with commit + push to the team repo (default: yes — Enter or y). Skip git with n on the push prompt or --no-git.

After push: teammates run sa sync. Optional --push / -y: skip prompts.

Publish pending — sa pending push

sa pending push 2026-06-02-my-slug.md
sa pending push              # unstaged pending/*.md
# flags: --all --dry-run --no-git

Commits/pushes team repo only when team mode is active.

Review — sa review

sa review list
sa review dry 2026-06-02-my-slug.md
sa review                    # interactive file picker
sa review 2026-06-02-my-slug.md

Prompt: [y] approve (move to approved/, update index.yaml, commit + push) · [r] reject (delete pending file, commit + push) · [n] cancel (file stays in pending/). Team repo only when team mode is active. -y still means approve.

Resolve path — sa pending path

sa pending path 2026-06-02-my-slug
# → …/team/learnings/pending/2026-06-02-my-slug.md  (with team repo)

Unapprove — sa unapprove

sa unapprove list
sa unapprove fantasy-2026-06-dragon-cache
# wizard: [1] Delete  [2] Move to pending/  [q] Cancel

Alias: sa unapprove = sa rm (remove learning, not uninstall repo)

Learning usage — sa learning (machine tracking, no review)

Each approved learning is a folder: learning.md (human-gated) + usage.yaml (machine-written events). Two report domains: opened/used/not_used/outdated = knowledge quality · read = agent telemetry (never mixed).

sa learning report --id crm-2026-07-ci-pre-commit-checks --event used --project crm-system --task t4821 --agent pi
sa learning report --id <id> --event outdated --note "ddev 1.23 changed behavior"
# events buffer in learnings/.usage-local.yaml; flushed by sa sync / sa learning push
sa learning status          # metrics + flags: OUTDATED · LOW-FIT · RULE-CANDIDATE · UNRESOLVED
sa learning events <id>     # raw events (remote + buffered)
sa learning migrate         # one-time folder migration (idempotent)

• outdated requires --note. Secrets in --note/--task are blocked.
• opened dedupes per (learning, task). Conflicts auto-resolve (union + eid dedup).
• Events for removed learnings → usage-orphan.yaml (quarantine, shown in sa learning status).

Uninstall — sa uninstall

sa uninstall
sa uninstall -y
sa uninstall --keep-repo     # adapters only; keep core + team/
sa uninstall --dry-run

Removes hooks and skill symlinks (Core and team skills). Without --keep-repo: deletes $SHARED_AGENTS_HOME including team/ and config.local.yaml.

Then open a new terminal, or source the updated rc (~/.bashrc, ~/.zshrc, or ~/.config/fish/config.fish). Fresh setup: sa bootstrap.

Team repo — sa team verify

After bootstrap or when debugging team layout:

sa team verify
sa team verify --json
sa team verify --strict      # exit 1 on warnings

Checks: team/.git, origin vs config.local.yaml, learnings/index.yaml, pending/ / approved/, legacy ~/shared-agents/learnings/.

Migration — sa team migrate

If ~/.shared-agents/learnings/ still exists (pre Core/team split):

sa team migrate --dry-run
sa team migrate

See $SHARED_AGENTS_HOME/docs/migration-team-data.md.

Troubleshooting

Agent instruction

When the user needs CLI help:

1. Run sa help (live text from scripts/sa_ui.py).
2. Use this skill for workflows — do not invent a parallel command list.
3. Paths: $SHARED_AGENTS_HOME — see skills shared-agents-knowledge and capture-learning.

More docs: $SHARED_AGENTS_HOME/README.md · docs/canonical-paths.md