CLI
Global Flags
Flags and environment variables that work on every poly command.
Every poly command accepts these flags, and each one can also be set through an environment variable — handy for scripts, CI, and agent harnesses where you want a behavior applied to every command.
Output & diagnostics
| Flag | Env var | Description |
|---|---|---|
-o, --output <pretty|json> | POLY_OUTPUT | Output format. pretty (default) renders colored, human-readable tables; json emits the same data as JSON for scripts. |
--color | POLY_COLOR | Force ANSI color, even when output isn't a terminal. Conflicts with --no-color. |
--no-color | POLY_NO_COLOR | Disable color. The ambient NO_COLOR convention is honored too, and JSON output is never colored. |
-v, --verbose <LEVEL> | POLY_VERBOSE | Log level: error, warn (default), info, debug, or trace. |
--timeout-ms <MS> | POLY_TIMEOUT_MS | Override each command's default timeout. |
Offline & staleness
These control how commands balance the local cache against the server — the full model is explained in How it Works.
| Flag | Env var | Description |
|---|---|---|
--cache-only | POLY_CACHE_ONLY | Only use the local cache. Reads fail if the data isn't cached; writes are queued and return without waiting for a server response. |
--no-stale | POLY_NO_STALE | Never accept possibly-stale local data. Reads fail rather than fall back to unconfirmed cache; writes wait for server confirmation before returning. |
Waiting for processing
| Flag | Env var | Description |
|---|---|---|
--wait-for-indexing | POLY_WAIT_FOR_INDEXING | After any write (and on file show/file read), wait until the file has been indexed for search. Indexing errors don't fail the command. |
--wait-for-transcoding | POLY_WAIT_FOR_TRANSCODING | Also wait for derived artifacts — video variants, PDF transcriptions. These can take minutes to hours; combine with --timeout-ms deliberately. |
Safety
| Flag | Env var | Description |
|---|---|---|
--disallow-force | POLY_DISALLOW_FORCE | Refuse irreversible actions that would otherwise be forced through — rm --force on archived files, rmdrive --force. Designed for agent harnesses. Once on (via flag, env var, or config file), it cannot be turned off from the command line. |
Configuration
| Flag | Env var | Description |
|---|---|---|
-c, --config <PATH> | POLY_CONFIG | Layer a TOML config file over the built-in defaults. The safety and staleness flags above can be set there as durable defaults. |
--config.<key>=<value> | — | Override a single config key inline, e.g. --config.daemon.binary_path=/opt/poly/poly. Highest precedence. |
Environment variables
Every global flag has an environment-variable twin, listed in the tables above. A few rules govern how they interact:
- Precedence — an explicit flag beats its environment variable, which beats the config file, which beats the built-in defaults. So
POLY_OUTPUT=json poly ls --output prettyrenders pretty. - Boolean parsing — boolean variables accept
1/true/yes/onand0/false/no/off, soPOLY_CACHE_ONLY=1andPOLY_CACHE_ONLY=trueare equivalent. - One-way safety —
POLY_DISALLOW_FORCEis the exception to precedence: like its flag, it can only switch the protection on. No flag or variable can switch it back off once any layer has enabled it. - Discoverability —
poly --helpannotates each flag with its[env: …]variable, so the CLI itself is always the up-to-date reference.
Examples
# Script-friendly: JSON output, no color, fail on stale data
POLY_OUTPUT=json POLY_NO_STALE=1 poly ls //Home
# Upload and block until the file is searchable
poly cp ./notes.md //Home/notes/ --wait-for-indexing
# A hardened environment for an agent
export POLY_DISALLOW_FORCE=1
export POLY_TIMEOUT_MS=30000
# Work fully offline from the local cache
poly find //Home -name "*.pdf" --cache-only