supercli-mastery

Files (1)

• SKILL.md

SKILL.md (first lines)

# 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

| Capability | Description |
|---|---|
| `commands` | Query available commands |
| `plugins` | Plugin management and discovery |
| `skills` | Agent-facing skill documents |
| `inspect` | View command schema |
| `plan` | Preview execution steps before running |
| `ask` | LLM suggests which commands to run (no execution) |
| `mcp` | Model Context Protocol adapter |

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

| Code | Meaning | Agent action |
|---|---|---|
| 0 | Success | Proceed |
| 82 | Validation error | Fix input arguments |
| 85 | Invalid argument | Fix the args, don't retry |
| 91 | Safety violation | Non-TTY interactive command blocked |
| 92 | Resource not found | Use different ID/name |
| 105 | Integration / API error | Retry with backoff (transient) |
| 110 | Internal error | Report bug, don't retry |

> 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

```

From javimosch/supercli, MIT.

More from javimosch/supercli