> ## Documentation Index
> Fetch the complete documentation index at: https://docs.agentpowers.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Usage

> Complete reference for the `ap` command-line tool

## Installation

<Tabs>
  <Tab title="npx (Recommended)">
    ```bash theme={null}
    npx @agentpowers/cli setup
    ```

    Auto-configures MCP for all detected AI tools. Also provides `search`, `install`, `login`, and `update` commands. Requires Node.js 18+.
  </Tab>

  <Tab title="Claude Code MCP">
    ```bash theme={null}
    claude mcp add agentpowers -- npx -y @agentpowers/mcp-server
    ```

    Adds AgentPowers as an MCP server in Claude Code.
  </Tab>

  <Tab title="pip">
    ```bash theme={null}
    pip install agentpowers
    ```

    Installs the `ap` CLI command globally. Still supported but npx is preferred.
  </Tab>
</Tabs>

Verify the installation:

```bash theme={null}
ap --version
```

## Authentication

```bash theme={null}
ap login     # Opens browser for OAuth sign-in
ap whoami    # Check current session
ap logout    # Clear stored token
```

The CLI uses long-lived tokens stored locally with restricted permissions, so you rarely need to re-login.

## Profile Management

Before you can publish a skill, you need a display name. Set it with `ap profile --set`:

```bash theme={null}
ap profile          # View your current profile
ap profile --set    # Interactively set your display name and bio
```

**View** shows your display name, email, bio, and join date. If no display name is set, a hint is shown.

**Set** prompts for display name and bio. Press `Ctrl-C` to cancel.

<Tip>
  `ap publish` will automatically prompt you to set a display name inline if you haven't done so yet — no need to run `ap profile --set` separately.
</Tip>

## Searching

```bash theme={null}
ap search "code review"
```

Returns a unified table with columns: Slug, Title, Source, Type, Price, Security, Installed. Results are sectioned by source -- AgentPowers native skills appear first, followed by external sources like ClawHub. Install counts and star ratings are shown inline in the Title column when available. The Installed column shows **Yes** (green), **Edited** (yellow for locally modified skills), or **No**.

Options:

```bash theme={null}
ap search "testing" --limit 10
ap search "devops" --category development
ap search "agent" --type agent
```

## Skill Detail

View full details for any skill:

```bash theme={null}
ap detail my-skill
```

The detail view includes star ratings when available (e.g., `Rating: ★★★★☆ (4.2 avg, 15 reviews)`).

Options:

| Flag             | Description                                                                   |
| ---------------- | ----------------------------------------------------------------------------- |
| `--source`, `-s` | Target a specific source (e.g., `clawhub`)                                    |
| `--scan`         | Download and run the full security pipeline, then display per-finding results |

```bash theme={null}
ap detail ontology --source clawhub
ap detail ontology --scan              # Deep security scan
```

## Installing Skills

### Free Skills

```bash theme={null}
ap install my-awesome-skill --scope user
```

Downloads and extracts to `~/.claude/skills/my-awesome-skill/`. Pass `--scope project` instead to land it under the current project's `.claude/skills/`.

### Paid Skills

```bash theme={null}
ap install premium-agent
```

Opens Stripe Checkout in your browser. After payment, the skill installs automatically.

### License Redemption

Use a license code to install on another machine:

```bash theme={null}
ap install premium-agent --code XXXXXXXX-XXXXXXXX-XXXXXXXX
```

### External Skills

Install skills from external sources like ClawHub:

```bash theme={null}
ap install ontology --source clawhub
```

External skills are downloaded to a sandbox, hashed, scanned through the full security pipeline, and only installed if they pass. See the [External Skills guide](/guides/external-skills) for details.

### Install Scope

Every `ap install` requires an explicit install scope — there is no default.

```bash theme={null}
ap install my-skill --scope user             # → ~/.claude/skills/my-skill/ (available everywhere)
ap install my-skill --scope project          # → ./.claude/skills/my-skill/ (only this project)
```

* **`--scope user`** — installs to `~/.claude/skills/`. The skill is available in every project you launch Claude Code from. Use this for general-purpose tools.
* **`--scope project`** — installs to `<cwd>/.claude/skills/`. The skill is only available when Claude Code is launched inside this project (or any subdirectory). Commit `.claude/skills/<slug>/` with your repo to share with your team.

If you omit `--scope` in an interactive terminal, the CLI prompts:

```text theme={null}
Install scope?
  [u] user — ~/.claude/skills (available everywhere)
  [p] project — ./.claude/skills (only this project)
>
```

In non-interactive contexts (scripts, CI), omitting `--scope` exits 1 with an actionable error.

The legacy `--global` flag still works as an alias for `--scope user`.

### Multi-Tool Install

Combine `--scope` with `--for` to install for a different AI tool:

```bash theme={null}
ap install my-skill --scope user --for codex          # ~/.codex/skills/my-skill/
ap install my-skill --scope project --for claude-code # ./.claude/skills/my-skill/
ap install my-skill --scope user --for agents         # ~/.agents/skills/my-skill/  (cross-client)
```

## Publishing

### 1. Create Your Skill

```text theme={null}
my-skill/
  SKILL.md      # Required: frontmatter with title, description, price
  ...            # Your skill files
```

### 2. Publish

```bash theme={null}
ap login
ap publish ./my-skill                    # Free skill (default)
ap publish ./my-skill --price 5.00       # Paid skill at $5.00
```

The CLI packages your directory as a ZIP, creates the skill record, and uploads the package. Your skill enters the security review pipeline automatically.

### 3. Publish Updates

Push new versions of an existing skill:

```bash theme={null}
ap publish ./my-skill --bump patch       # Default: patch bump
ap publish ./my-skill --bump minor       # Minor version bump
ap publish ./my-skill --bump major       # Major version bump
ap publish ./my-skill --version 2.0.0    # Explicit version
ap publish ./my-skill --changelog "Bug fixes and performance improvements"
ap publish ./my-skill --bump patch --price 9.99   # Update version + change price
```

The `--bump` and `--version` flags are mutually exclusive. The previous version stays live while the new version undergoes security review.

**Price behavior on updates:** Omitting `--price` preserves the current price. Only pass `--price` when you want to change it. Use `--price 0` to switch a paid skill to free.

## Updating Installed Skills

Keep installed skills up to date -- works for both native and external (e.g., ClawHub) skills:

```bash theme={null}
ap update                # Check all installed skills (native + external)
ap update my-skill       # Update a single skill
ap update --force        # Skip confirmation prompt
```

For external skills, updates go through the full sandboxed security pipeline (download → hash → scan → install), the same as the initial install.

Locally edited skills prompt before overwriting (default **No**):

```text theme={null}
# When a newer version is available:
my-skill has been locally edited.
Update my-skill anyway? Local changes will be overwritten [y/N]:

# When already at the latest version:
my-skill has been locally edited.
Restore my-skill to original? Local changes will be overwritten [y/N]:
```

Press Enter to skip, or `y` to overwrite. Use `--force` to bypass the prompt entirely. When updating all skills, each edited skill is prompted individually. The `Installed` column in `ap search` shows **Edited** (yellow) for modified skills.

## Scanning External Skills

Preview a skill's security status without installing it:

```bash theme={null}
ap scan ontology --source clawhub
```

This downloads the skill to a temporary sandbox, uploads it for a full security scan, displays the results, and cleans up. Nothing is installed.

If the source is omitted, the CLI auto-detects it:

```bash theme={null}
ap scan ontology
```

## Uninstalling Skills

```bash theme={null}
ap uninstall my-skill
```

Removes the skill from `~/.claude/skills/` (or `~/.claude/agents/` for agents).

## Unpublishing and Republishing

Archive a skill to hide it from marketplace search and listings:

```bash theme={null}
ap unpublish my-skill
```

Existing purchasers retain download access. To restore an archived skill:

```bash theme={null}
ap republish my-skill
```

Both commands require confirmation and can only be run by the skill author.

## ClawHub Claims

If you authored a skill on ClawHub, claim ownership:

```bash theme={null}
ap claim my-clawhub-skill
```

Claims are verified automatically.

## Verifying Installed Skills

External skills (from ClawHub and other sources) are pinned by content to protect against supply chain attacks. To verify that all installed skills match their recorded pins:

```bash theme={null}
ap verify
```

This checks each installed skill's current content hash against the recorded pin and alerts you to any mismatches.

## Command Reference

| Command               | Description                                                                           |
| --------------------- | ------------------------------------------------------------------------------------- |
| `ap login`            | Authenticate via browser OAuth                                                        |
| `ap logout`           | Clear stored credentials                                                              |
| `ap whoami`           | Show current user                                                                     |
| `ap profile`          | View your seller profile (display name, bio)                                          |
| `ap profile --set`    | Interactively update display name and bio                                             |
| `ap search <query>`   | Search the marketplace (unified, sectioned results)                                   |
| `ap detail <slug>`    | View skill or agent details (`--source`, `--scan` flags)                              |
| `ap install <slug>`   | Install a skill (`--scope` required; `--code`, `--source`, `--for`, `--global` flags) |
| `ap publish <path>`   | Publish or update a skill (`--price`, `--bump`, `--version`, `--changelog` flags)     |
| `ap update [slug]`    | Update installed skills to latest versions (`--force` flag)                           |
| `ap scan <slug>`      | Scan an external skill without installing                                             |
| `ap uninstall <slug>` | Remove an installed skill                                                             |
| `ap unpublish <slug>` | Archive a published skill (hide from marketplace)                                     |
| `ap republish <slug>` | Restore an archived skill to the marketplace                                          |
| `ap claim <slug>`     | Claim a ClawHub skill                                                                 |
| `ap status`           | Show installed skills and agents with their status                                    |
| `ap verify`           | Verify installed skills against content hash pins                                     |

## Need Help?

<CardGroup cols={2}>
  <Card title="Email Support" icon="envelope" href="mailto:support@agentpowers.ai">
    Reach us at **[support@agentpowers.ai](mailto:support@agentpowers.ai)** for account issues, billing questions, or technical help.
  </Card>

  <Card title="Discord Community" icon="discord" href="https://discord.gg/ECAzvrvHA">
    Join the **AgentPowers Discord** to get help from the team and other creators in real time.
  </Card>
</CardGroup>