# CLI command reference

> Markdown variant of <https://www.skillzdrive.com/docs/cli/reference>.

Every `skillzdrive` command. Grouped by purpose. Auth tags:

- **Anonymous ✓** — works without `skillzdrive login`.
- **Auth required** — must be logged in (or pass `SKILLZDRIVE_API_KEY=...`).

## Global flags + environment

- `SKILLZDRIVE_API_BASE` — override API host. Defaults to `https://www.skillzdrive.com`.
- `~/.skillzdrive/install_id` — per-machine UUID sent as `X-Skillzdrive-Install-Id`. Generated on first run.
- `--help` / `-h` — on any command.
- `--version` / `-V` — print CLI version.

## Discover

### `skillzdrive search <query>` — Anonymous ✓

Search the public catalog. Anonymous requests rate-limited to 1/min.

```bash
skillzdrive search pdf
skillzdrive search "document" --limit 10
```

Flags: `--limit <n>` (default 20, cap 50).

### `skillzdrive show <slug>` — Anonymous ✓

Print metadata + download info for a single public skill.

### `skillzdrive discover <keywords>` — Auth required

Broader search across marketplace + GitHub, paginated 10 per page.

```bash
skillzdrive discover pdf
skillzdrive discover document --offset 10
```

### `skillzdrive leaderboard` — Auth required

Top 10 skills by the chosen sort dimension. Flags:
`--sort-by executions|installs|rating` (default `executions`).

## Local drive (canonical + symlinks)

Manage what's on this machine and linked into this project. No
server state.

### `skillzdrive install <source>` — Anonymous ✓

Install a skill into the canonical drive and symlink into this
project.

```bash
# By slug (uses SkillzDrive hosted artifact if available)
skillzdrive install pdf

# Direct GitHub
skillzdrive install github:anthropics/skills/skills/docx
skillzdrive install https://github.com/foo/bar

# Local path (BYO)
skillzdrive install ./my-skill

# Reinstall from the project's lockfile
skillzdrive install --frozen
```

Flags: `--agents claude,codex,gemini,goose,universal` (auto-detected
if omitted), `--frozen`.

### `skillzdrive list` / `ls` — Anonymous ✓

List canonical-drive skills.

### `skillzdrive remove <slug>` / `rm` — Anonymous ✓

Remove the canonical copy (symlinks in projects become dangling —
clean up with `unlink`).

### `skillzdrive link <slug>` — Anonymous ✓

Symlink an already-installed drive skill into this project without
re-downloading.

```bash
skillzdrive link pdf --agents claude,codex
```

### `skillzdrive unlink <slug>` — Anonymous ✓

Remove this project's symlinks for a drive skill. Canonical copy
untouched.

### `skillzdrive scaffold [name]` — Anonymous ✓

Create a new skill author project in `./<name>/` following the
agentskills.io spec.

```bash
skillzdrive scaffold my-new-skill
# → ./my-new-skill/{SKILL.md, scripts/hello.sh, references/, README.md}
```

## Auth + account

### `skillzdrive login` — Anonymous ✓

Store your API key in the OS keychain + claim your anonymous
install_id for this account.

```bash
skillzdrive login --token sk_live_...
# Without --token, prompts interactively.
```

### `skillzdrive logout` — Anonymous ✓

Clear the stored API key.

### `skillzdrive whoami` — Anonymous ✓

Print install_id + auth status + (if authenticated) a round-trip
key check.

### `skillzdrive credits` — Auth required

Balance, tier, monthly skill-call usage + limit, last 10
transactions.

## Workflows

### `skillzdrive sync` — Auth required

Pull your entire hosted drive into the canonical local drive.
Installs new, updates changed, skips unchanged.

### `skillzdrive init --defaults` — Anonymous ✓

Pull the SkillzDrive recommended starter set into this project.
Zero signup.

```bash
skillzdrive init --defaults
skillzdrive init --defaults --agents claude,codex
```

### `skillzdrive update [slugs...]` — Auth required

Re-fetch latest artifacts for listed skills, or all lockfile
entries if none given.

```bash
skillzdrive update                # all lockfile entries
skillzdrive update pdf docx
```

### `skillzdrive audit` — Auth required

Verify every lockfile entry is present on disk + check server for
updates. Non-zero exit only on missing skills.

### `skillzdrive run <slug> <script> [args...]` — Auth required

Execute a skill script in the hosted E2B sandbox. Blocking — prints
stdout/stderr on completion.

```bash
skillzdrive run pdf extract.sh -- input.pdf output.txt

# With stdin
skillzdrive run pdf process.sh --stdin "some input"

# Persistent sandbox session across calls
skillzdrive run pdf init.sh --reuse
skillzdrive run pdf step2.sh --session-id <from-previous-call>
```

Flags: `--stdin <str>`, `--session-id <id>`, `--reuse`.

## `drive` subcommand — hosted drive

```bash
skillzdrive drive list                 # list hosted drive
skillzdrive drive list --collection X  # filter to named collection
skillzdrive drive add <slug>           # import a marketplace skill or GitHub URL
skillzdrive drive remove <slug>        # remove from hosted drive
skillzdrive drive toggle <slug>        # flip enabled flag without removing
```

## `updates` subcommand

```bash
skillzdrive updates list               # pending updates for your drive
skillzdrive updates accept <slug>      # apply the update (may charge credits)
skillzdrive updates dismiss <slug>     # dismiss; no charge
```

## `collections` subcommand

A collection is a named API key that scopes a subset of your drive.
Publish one as a public marketplace to share with end-users.

```bash
skillzdrive collections list
skillzdrive collections create <name>                        # all-skills collection
skillzdrive collections create <name> --skills pdf,docx      # scoped collection
skillzdrive collections create <name> --skills pdf --include-team --include-shared
skillzdrive collections update <name> --rename <newName>
skillzdrive collections update <name> --skills pdf,docx      # replace skill list
skillzdrive collections add <name> <slug>                    # add one skill
skillzdrive collections remove <name> <slug>                 # remove one skill
skillzdrive collections publish-marketplace <name>           # expose as /marketplace/collections/<name>.json
skillzdrive collections publish-marketplace <name> --unpublish
```

`create` prints the generated `sk_live_*` for the new collection
exactly once — save it. That's the key the collection's end-user
will use to access only the scoped subset of your drive.

## `webhooks` subcommand

Credit-alert webhook subscriptions. See the
[Webhooks guide](https://www.skillzdrive.com/docs/rest-api/webhooks.md)
for payload + verification details.

```bash
skillzdrive webhooks list
skillzdrive webhooks create \
  --event credits.threshold_hit \
  --url https://example.com/hooks/skillzdrive \
  --threshold 500
skillzdrive webhooks create \
  --event credits.exhausted \
  --url https://example.com/hooks/skillzdrive
skillzdrive webhooks delete <id>
```

## Authoring + info

### `skillzdrive upload <path>` — Auth required

Upload a local `.zip` or `.skill` file to your drive. Replicates
the upload-ticket flow inline — no bash, no shell-history token
exposure.

```bash
skillzdrive upload ./my-skill.zip
skillzdrive upload ./my-skill.zip --collection acme-team
```

### `skillzdrive scan [slug]` — Anonymous ✓

Info about SkillzDrive's server-side security scans. Anonymous
mode is an upsell prompt; authenticated mode points at your
dashboard.

## Exit codes

| Code | Meaning |
|------|---------|
| 0 | Success. |
| 1 | Generic failure (API error, validation, missing files, SHA mismatch, etc.). Inspect stderr for the error code. |
| `<script exit>` | `run` returns the script's exit code when the server reports one. |

Structured errors print to stderr with `Error [code]: message` plus
an upsell URL when applicable. Pipe `2>` to capture.