CLI

Agent Skill

Give AI agents the poly CLI — through the polymcp integration or the hosted MCP server.

The CLI was designed to be driven by AI agents as much as by people. Poly's agent integration ships as polymcp. It's a plugin repo containing an MCP server configuration plus the poly-cli agent skill, which teaches an agent how to search, read, create, update, and organize your Poly files by composing poly commands.

Installing

Installation depends on the tool your agent runs in. The repo withpoly/polymcp covers most of them:

# Claude Code
claude plugin marketplace add withpoly/polymcp
claude plugin install poly@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:

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 give an agent the same command surface, with one meaningful difference:

	Local (`poly` CLI)	Hosted (`mcp.poly.app`)
Requires the desktop app	Yes	No
Works on your local sync folder paths	Yes	No — Poly refs only (`//Home/…`, links)
Offline capable	Yes (cache-backed)	No
Tools exposed	Everything in the command reference	`search`, `fetch`, and a `cli` tool mirroring the same commands

The hosted server's cli tool is a virtual poly command line: an agent can run ["--help"] to discover commands, and the flags and help text match the desktop CLI exactly.

How the skill composes commands

Because every command has stable flags, JSON output, and meaningful exit codes, agents can chain them the same way you would in a shell:

# 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 archives rather than deletes, anything an agent removes is recoverable from your Archive — see Recovering Files.

Global Flags

Flags and environment variables that work on every poly command.

Our Privacy Commitment

How Poly handles your data, what we store, and what we never do with it.