CLI

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 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, Poly for Codex, Poly for Hermes, and 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:

# 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:

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:

	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 for supported remote commands

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 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.