Sa Cli

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
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

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)

| Area | Command | Summary | |------|---------|---------| | Info | sa · sa help | All commands | | Info | sa version | CLI version + HOME | | Setup | sa bootstrap | Full first-time setup (Core + team + adapters) | | Setup | sa install | Setup wizard (default in TTY) | | Setup | sa install --non-interactive | All detected tools, no prompts | | Setup | sa install --wizard | Wizard explicitly | | Setup | sa check | Tool installed vs configured (+ team warnings) | | Setup | sa sync | Pull Core + team; link skills + rules | | Setup | sa status | Open items: review, skills, adapters, team | | Setup | sa doctor | Diagnose symlink / rule link issues | | Setup | sa doctor --fix | Repair (backup + relink blocking rule files) | | Setup | sa team verify | Deep team repo validation | | Setup | sa team migrate | Legacy learnings/ → team/learnings/ | | Setup | sa uninstall | Uninstall (y/N) | | Learnings | sa review | Interactive: pending → approved | | Learnings | sa review list | Pending list | | Learnings | sa review dry [file] | Dry-run | | Learnings | sa pending push [file] | Commit + push pending | | Learnings | sa pending path [slug] | Canonical pending path | | Learnings | sa unapprove [id\|file] | Remove from approved | | Learnings | sa unapprove list | Approved list | | Team content | sa skill new | Wizard: team/skills//SKILL.md | | Team content | sa skill rm [name] | Remove team skill | | Team content | sa skill list | List team skills | | Team content | sa skill edit [name] | Edit team skill (opens $EDITOR) | | Team content | sa rule new | Wizard: team/rules/.mdc | | Team content | sa rule rm [slug] | Remove team rule | | Team content | sa rule list | List team rules | | Team content | sa rule edit [slug] | Edit team rule (opens $EDITOR) |

Alias: sa install = sa setup

---

Status — sa status

Shows easy-to-forget work:

| Check | Meaning | Action | |-------|---------|--------| | Pending learnings | team/learnings/pending/ (team repo) | sa review list · sa review | | Not pushed yet | Local pending changes | sa pending push | | Team setup | Config / legacy layout | sa team verify · sa team migrate | | Skill symlinks | New skill not linked | sa sync · sa doctor --fix | | Rule symlinks | Missing link or local file blocks symlink | sa doctor --fix · sa sync | | Adapters | Tool present, not configured | sa install |

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

| Step | Controls | |------|----------| | Install path | Type path · Enter | | Agents | ↑↓ · Space toggle · a all · d detected · Enter | | Team repo URL | Optional private remote for learnings | | Shell CLI | ←→ / ↑↓ Yes/No · Enter | | Summary | ↑↓ Run/Cancel · Enter (default: Cancel) |

• 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)

| Flag | Meaning | |------|---------| | --home DIR | Target path (default: ~/.shared-agents) | | --source DIR | Source repo (dev checkout) | | --shell-rc FILE | bashrc for SHARED_AGENTS_HOME + sa | | --tools IDS | Comma-separated adapter IDs only | | --check | Status instead of install (sa check) | | --check --json | JSON for CI | | --dry-run | Preview, no writes |

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

---

Check — sa check

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

| STATUS | Meaning | |--------|---------| | ok | Tool present + shared-agents configured | | missing_tool | CLI/config not found | | not_configured | Tool present, adapter missing → sa install | | available | generic fallback |

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, Codex, Claude Code (~/.claude/CLAUDE.md), Gemini, Windsurf, …: merged `` 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

| Flag | Meaning | |------|---------| | --domain DOMAIN | Target under approved/by-domain/ | | --dry-run | Show only | | --no-git | No commit/push | | -y / --yes | Skip confirmation |

Moves to team/learnings/approved/, updates index.yaml, commit + push (team repo only in team mode).

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

| Flag | Meaning | |------|---------| | --to-pending | Move to pending/ (non-interactive) | | --delete | Delete file (non-interactive) | | --dry-run · --no-git · -y | same as review |

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

---

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: source ~/.bashrc or new terminal. 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

| Problem | Fix | |---------|-----| | sa: command not found | source ~/.bashrc or "$SHARED_AGENTS_HOME/scripts/sa" help | | shared-agents not installed | sa bootstrap or sa install / ./sa install | | Tool not_configured | sa install | | Stale learnings | sa sync · check hooks / sa check | | Team layout / legacy paths | sa team verify · sa team migrate | | Wizard cancelled, half setup | rm -rf ~/.shared-agents · sa bootstrap again |

---

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

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: netgrade-digital
• Source: netgrade-digital/shared-agents
• License: MIT
• Homepage: https://netgrade-digital.github.io/shared-agents/

Install and usage instructions live in the source repository linked above.