# SkillzDrive CLI

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

One command installs, manages, and runs agent skills anywhere.
Anonymous by default — signup only when you need to publish, execute
hosted skills, or sync a personal drive.

## Install

```bash
# No install
npx skillzdrive --help

# Global
npm install -g skillzdrive
skillzdrive --help
```

Requires Node.js ≥20. Stores credentials in the OS keychain (macOS
Keychain, Windows Credential Manager, libsecret on Linux) with a
0600-permission file fallback.

## First run — anonymous

Works in any empty directory:

```bash
# Browse the public catalog
skillzdrive search weather

# Inspect a skill before installing
skillzdrive show pdf

# Install directly from GitHub
skillzdrive install github:anthropics/skills/skills/docx

# See what's installed locally
skillzdrive list
```

## First run — authenticated

Sign in for hosted installs, collections, execution, and webhooks:

```bash
# Paste your sk_live_* key from the dashboard
skillzdrive login --token sk_live_...

# Sync your entire hosted drive to local
skillzdrive sync

# Run a skill in the hosted sandbox
skillzdrive run pdf extract.sh -- input.pdf

# Check your credit balance
skillzdrive credits
```

## The drive model

The CLI keeps a single canonical copy of each skill in
`~/.skillzdrive/drive/` and symlinks that copy into each project's
per-agent directory. One skill on disk, many agent-view symlinks,
zero duplication.

```
~/.skillzdrive/
├── drive/
│   ├── pdf/                      # canonical copy — one per skill
│   │   ├── SKILL.md
│   │   ├── scripts/
│   │   └── .skillzdrive-meta.json
│   └── docx/
├── install_id                     # anonymous telemetry identity
└── cache/                          # content-addressed zip cache

~/project-a/
├── .claude/skills/pdf  → symlink → ~/.skillzdrive/drive/pdf
├── .codex/skills/pdf   → symlink → ~/.skillzdrive/drive/pdf
└── skillzdrive.lock.json           # pinned SHAs for reproducibility

~/project-b/
└── .agent/skills/pdf   → symlink → ~/.skillzdrive/drive/pdf
```

**Agent auto-detection**: run `skillzdrive install <slug>` without
`--agents` and the CLI symlinks into every agent dir already present
in the project (`.claude/`, `.codex/`, `.gemini/`, `.agents/`).
Falls back to `.agent/skills/` (the cross-agent convention) if none
detected.

## Reproducible installs

Every install writes a `skillzdrive.lock.json` at the project root
with the exact content SHA. Commit it, and your team + CI can
rebuild byte-identical installs:

```bash
# Fresh checkout
skillzdrive install --frozen
skillzdrive audit           # verifies presence + server drift, exits non-zero on missing skills
```

## Anonymous limits

Anonymous mode exists so you can try the CLI with zero friction —
but it's deliberately narrow. You hit signup pressure exactly when
you ask for something only an account can do.

| Capability | Anonymous | Authenticated |
|------------|-----------|---------------|
| Install public skills | 10 total | Per tier |
| Install `github:` skills | ✓ | ✓ |
| Install local skills (BYO) | ✓ | ✓ |
| Search the catalog | 1/min rate-limited | 600/min |
| Run hosted executions | — | ✓ (per tier) |
| Upload / publish | — | ✓ |
| Collections + teams | — | ✓ |
| Webhooks | — | ✓ |
| Credits | — | ✓ |

## Telemetry

The CLI sends anonymous telemetry on `install`, `sync`, `update`,
`audit`, `scan`, and `init`. It contains your install_id UUID
(generated on first run and stored at
`~/.skillzdrive/install_id`), the CLI version, OS string, and the
slugs of skills you operated on. No PII.

When you log in, the CLI claims the install_id for your account so
you get security alerts for skills you previously installed
anonymously.

## See also

- [Full command reference](https://www.skillzdrive.com/docs/cli/reference.md): every command + flag, with examples.
- [REST API](https://www.skillzdrive.com/docs/rest-api.md): the CLI is a thin client over this HTTP API.