# SkillDock CLI Usage

Guide to install the SkillDock CLI and work with skills from skilldock.io: authenticate, search, inspect details, and install.

## Inputs
- Optional: `BASE_URL` (default `https://api.skilldock.io`)
- Optional: `OPENAPI_URL` (default `https://api.skilldock.io/openapi.json`)
- Optional: `SKILLS_DIR` (default OpenClaw workspace skills folder)

## 1) Install the CLI

Preferred (pipx):
```bash
pipx install --force skilldock
skilldock --version
```

Fallback (pip, user mode):
```bash
python3 -m pip install --user --upgrade skilldock
skilldock --version
```

## 2) Configure endpoints (optional)
```bash
skilldock config set --base-url "$BASE_URL" --openapi-url "$OPENAPI_URL"
skilldock config show
```

## 3) Authenticate (Google OAuth)
```bash
skilldock auth login           # opens browser
skilldock auth login --no-open # prints approval URL if headless
skilldock auth status
```

## 4) Make SkillDock the default source for OpenClaw skills

The goal: whenever you ask me to find/install/update/remove your skills, I use SkillDock and put them into OpenClaw’s default skills folder.

### 4.1) Install to the default OpenClaw skills directory
In this workspace, the default skills folder is:
```
/Users/evgeniievstafev/clawd/skills
```
Install any skill there so OpenClaw can discover it automatically:
```bash
skilldock install <namespace>/<slug> --skills-dir "/Users/evgeniievstafev/clawd/skills"
```

### 4.2) Tell OpenClaw to refresh skills
After install/update/remove, refresh skill discovery:
- Ask the agent: “refresh skills”, or
- Restart the gateway.

### 4.3) How to ask the assistant (example prompts)
Use explicit instructions like:
- “Find a SkillDock skill for X, install it to default skills dir, and refresh skills.”
- “Update my SkillDock skill <namespace>/<slug> to the latest version and refresh skills.”
- “Uninstall SkillDock skill <namespace>/<slug> from the default skills dir.”
- “Publish a new version of my SkillDock skill <namespace>/<slug> from this repo.”

## 5) Search skills on skilldock.io
Free-text search:
```bash
skilldock skills search "docker"
```

Filter by namespace/tag:
```bash
skilldock skills search --namespace "skilldock" --tag "cli"
```

Machine-readable JSON:
```bash
skilldock skills search "docker" --json
```

## 6) Inspect a skill
```bash
skilldock skill show skilldock/skilldock-publisher
```
(Shows summary, tags, homepage_url if set.)

## 7) Optional: set a background image URL (publisher)
Requires auth on a skill you own. The API currently accepts `background_image_url`.
```bash
skilldock request PATCH "/v1/skills/<namespace>/<slug>" \
  --json '{"background_image_url":"https://example.com/image.png"}'
```
Tip: use HTTPS URLs; the backend may proxy/normalize the image URL.

## 8) Install a skill
Latest version:
```bash
skilldock install acme/my-skill --skills-dir "/Users/evgeniievstafev/clawd/skills"
```

Specific version:
```bash
skilldock install acme/my-skill --version 1.2.3 --skills-dir "/Users/evgeniievstafev/clawd/skills"
```

Custom skills directory (if you really want a different folder):
```bash
skilldock install acme/my-skill --skills-dir "$SKILLS_DIR"
```

## 9) List installed skills
```bash
skilldock install list
```

## 10) Uninstall a skill
```bash
skilldock uninstall acme/my-skill --skills-dir "/Users/evgeniievstafev/clawd/skills"
```

## 11) Update an owned skill and publish
1) Edit your local skill folder.
2) Bump `version:` in `SKILL.md`.
3) Verify and publish:
```bash
skilldock skill verify "/path/to/skill"
skilldock skill upload \
  --namespace "<namespace>" \
  --slug "<slug>" \
  --version "<new-version>" \
  --path "/path/to/skill"
```

## Troubleshooting
- `401/403`: re-run `skilldock auth login` or check token scopes.
- `404`: check namespace/slug/version spelling or visibility.
- Rate limits: wait 60s before retrying auth.