# Agent Skill

> Give AI agents the poly CLI through Poly's plugins or hosted MCP server.

The CLI was designed to be driven by AI agents as much as by people. The [`poly-cli` agent skill](https://github.com/withpoly/polycc/tree/main/plugin/skills/poly-cli) teaches an agent how to search, read, create, update, and organize your Poly files by composing `poly` commands. It ships in [Poly for Claude Code](https://github.com/withpoly/polycc), [Poly for Codex](https://github.com/withpoly/polycodex), [Poly for Hermes](https://github.com/withpoly/polyhermes), and [polymcp](https://github.com/withpoly/polymcp) for other clients.

## Installing

Installation depends on the tool your agent runs in. Claude Code, Codex, and Hermes have dedicated plugins that also load Poly memory when a session starts; polymcp covers the other supported clients:

```bash
# Claude Code
claude plugin marketplace add withpoly/polycc
claude plugin install poly@poly

# Codex
codex plugin marketplace add withpoly/polycodex
codex plugin add poly@poly

# Hermes
hermes plugins install withpoly/polyhermes --enable
hermes mcp login poly

# Gemini CLI
gemini extensions install https://github.com/withpoly/polymcp
```

- **Claude Desktop**: install the extension straight from the Poly desktop app (**Downloads → Install Claude Desktop extension**). Run **Install CLI Tools** first; the extension works by forwarding tool calls to your local `poly` binary.
- **Anything else that speaks MCP**: point the client at Poly's hosted MCP server:

```text
https://mcp.poly.app/mcp
```

The hosted server uses streamable HTTP and authenticates with OAuth. Your client opens a browser window on first connection, and no keys or tokens are pasted into config files.

## Local CLI vs. hosted MCP

Both paths let an agent perform core file operations, but hosted MCP exposes a smaller, remote-only command surface:

<table>
<thead>
  <tr>
    <th>
      
    </th>
    
    <th>
      Local (<code>
        poly
      </code>
      
       CLI)
    </th>
    
    <th>
      Hosted (<code>
        mcp.poly.app
      </code>
      
      )
    </th>
  </tr>
</thead>

<tbody>
  <tr>
    <td>
      Requires the desktop app
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      No
    </td>
  </tr>
  
  <tr>
    <td>
      Works on your local sync folder paths
    </td>
    
    <td>
      Yes
    </td>
    
    <td>
      No — Poly refs only (<code>
        //Home/…
      </code>
      
      , links)
    </td>
  </tr>
  
  <tr>
    <td>
      Offline capable
    </td>
    
    <td>
      Yes (<a href="/cli/how-it-works">
        cache-backed
      </a>
      
      )
    </td>
    
    <td>
      No
    </td>
  </tr>
  
  <tr>
    <td>
      Tools exposed
    </td>
    
    <td>
      Everything in the <a href="/cli/commands">
        command reference
      </a>
    </td>
    
    <td>
      <code>
        search
      </code>
      
      , <code>
        fetch
      </code>
      
      , and a <code>
        cli
      </code>
      
       tool for supported remote commands
    </td>
  </tr>
</tbody>
</table>

The hosted server's `cli` tool is a virtual remote Poly command line: run `["--help"]` to discover its available commands and flags. Desktop-only operations such as version history and restores, deep folder copies, and direct byte access are unavailable.

## How the skill composes commands

Because every command has stable flags, [JSON](/mime-types/application/json) output, and meaningful exit codes, agents can chain them the same way you would in a shell:

```bash
# Find the file, inspect it, then read just the relevant pages
poly search "signed lease agreement" --limit 3 --output json
poly file show //Home/legal/lease.pdf
poly file read //Home/legal/lease.pdf --pages "3-5"

# Organize: tag everything the search returned
poly search --include-type pdf --under //Home/inbox --output json \
  | jq -r '.[].id' \
  | xargs -I{} poly file update {} --tag blue:to-file
```

## Safety for agent harnesses

Two global flags exist specifically for agents:

- **--disallow-force** (or `POLY_DISALLOW_FORCE=1`) — refuses any irreversible action that would otherwise be forced through. With it set, `rm` can only archive (never permanently delete), and confirmation prompts can't be bypassed. The polymcp integrations set this automatically.
- **--no-stale** — makes reads fail rather than return unconfirmed cached data, for workflows that must act only on server-confirmed state.

Since [`rm`](/cli/commands/rm) archives rather than deletes, anything an agent removes is recoverable from your Archive — see [Recovering Files](/recovering-files).