supercli-mastery — Agent's Guide to SuperCLI

What SuperCLI Is

SuperCLI is a capability router. It wraps external CLIs (plugins) behind a uniform namespace.resource.action command model. Every command follows the same pattern:

sc <namespace> <resource> <action> --<arg> <value> --json

The workflow is: discover → learn → inspect → plan → execute

Core Capabilities

Output Conventions

All commands return JSON when --json is used (or by default in non-TTY):

sc <ns> <res> <act> --json
→ { "version": "1.0", "command": "ns.res.act", "data": {...} }

• stdout: Primary data (JSON envelope)
• stderr: Progress events, warnings, structured errors
• Exit code 0: Success

Semantic Exit Codes

Range convention (Square-style): 80-89 input errors, 90-99 resource errors, 100-109 integration errors, 110-119 internal errors. Currently implemented codes listed above; unused slots reserved for future granularity.

Agent Workflow

1. Discover — Find what's available

sc --json
# → lists first_steps with {command, purpose} pairs

sc commands --query backup --limit 50 --json
# → { commands: [{ namespace, resource, action, description }] }

sc plugins explore --name <tool> --json
# → { plugins: [{ name, description, tags, installed }] }

2. Learn — Understand a plugin

sc plugins learn <name> --json
# → plugin metadata, commands, install guidance

sc skills get <name> --json
# → agent-facing SKILL.md content for that tool

3. Inspect — See a command's schema before using it

sc inspect <namespace> <resource> <action> --json
# → { namespace, resource, action, args: [{name, type, required, positional}], adapterConfig }

Inspect tells you:

• Which --flags are required vs optional
• Which args are positional (marked "positional": true)
• The adapter type (process, http, mcp, shell)
• Timeout and safety settings

4. Plan — Preview before executing mutations

sc plan <namespace> <resource> <action> --<args> --json
# → { plan_id, command, steps, risk_level, side_effects, persisted }

plan does NOT execute — it returns a plan document showing:

• The 4 execution steps (resolve → validate → adapter → transform)
• risk_level: "safe" for reads, "medium" for mutations
• side_effects: true for write operations

Use plan before any command that modifies state.

5. Execute — Run commands

# Direct execution (no server)
sc <namespace> <resource> <action> --<arg> <value> --json

# Or via persisted plan (with SUPERCLI_SERVER)
sc plan <ns> <res> <act> --<args> --json
sc execute <plan_id> --json

Ask — LLM suggests a plan

sc ask "send an email to user@example.com"
# → { mode: "ask_suggest", suggested_steps: [{ command, args, dry_run }] }

ask uses an LLM to map natural language to supercli commands. It NEVER executes — returns suggestions with dry_run strings you can choose to run.

Working with Output

Always use --json for machine-readable output:

# Pipe to jq for extraction
sc commands --query backup --json | jq '.commands[].namespace'

# Chain commands
sc easyredmine issue search "correction" --current-month | \
  jq -r '.results[].id' | \
  xargs -I {} sc easyredmine issue show {} --json

Error responses are always on stderr:

sc nonexistent command --json
# stderr: {"error":{"code":92,"type":"resource_not_found","message":"...","recoverable":false,"suggestions":["Run: supercli commands"]}}

Token Optimization

For large outputs (50+ files, long command results), use context-mode:

sc mcp call --mcp-server context-mode --tool ctx_batch_execute --input-json '...' --json

See sc skills get context-mode:quickstart --json for context-mode usage.

Skills System

Skills are agent-facing documents that teach you how to use tools:

sc skills sync --json                    # index all skills
sc skills list --catalog --limit 10      # browse
sc skills search --query <topic>         # find by topic
sc skills get <id>                       # read a skill

Skills come from:

• plugin_fs: Bundled with supercli plugins (plugins/<name>/skills/quickstart/SKILL.md)
• local_fs: From provider-scanned directories (e.g. ~/.config/opencode/skills/)
• supercli: Built-in skills shipped with the supercli package itself

Navigation Pattern

When you don't know a command's namespace:

# 1. Browse capabilities
sc --json

# 2. Search commands
sc commands --query <keyword> --json

# 3. Inspect the most promising match
sc inspect <ns> <res> <act> --json

# 4. Plan if it's a write operation
sc plan <ns> <res> <act> --args

# 5. Execute
sc <ns> <res> <act> --args --json

Key Principles

1. --json everywhere — all commands support it
2. Plan before write — use plan for any command that might have side effects
3. Inspect before run — check args and positional markers in inspect output
4. Errors are structured — always on stderr with code, type, recoverable, suggestions
5. Skills teach you — if you don't know a tool, sc skills search --query <tool>
6. Exit codes drive decisions — 85=fix args, 92=try different resource, 105=retry