CLI Reference

Commands and flags for running and configuring Polytoken from a shell.

The legacy top-level print commands remain available for compatibility. Use the polytoken print command group for new scripts and workflows.

polytoken

Polytoken CLI.

Argument	Type	Description
--config-dir	CONFIG	Config directory for this invocation.
--working-dir	WORKING_DIR	Working directory for this invocation.

polytoken config

Validate and manage Polytoken configuration.

polytoken config ui

Open the interactive configuration shell.

polytoken config edit

Edit a Polytoken configuration file, then validate it.

Argument	Type	Description
--user	flag	Edit the user/global config layer instead of the current project layer.
--format	yaml, toml, json5	Format to use when creating a missing config file. Default: yaml.

polytoken config validate

Validate Polytoken configuration files.

Argument	Type	Description
--user	flag	Validate only the user/global config layer.
--project	flag	Validate only the current project’s config layer.

polytoken auth

Manage provider authentication state.

polytoken auth mcp

Manage authentication for a configured MCP server.

polytoken auth mcp login

Log in to a configured MCP server with OAuth.

Argument	Type	Description
--server	SERVER	Configured MCP server name. Required.
--force	flag	Overwrite existing OAuth state without prompting.
--no-open	flag	Print the authorization URL without trying to open it in a browser.

polytoken auth mcp status

Show whether a configured MCP server has stored OAuth state.

Argument	Type	Description
--server	SERVER	Configured MCP server name. Required.

polytoken auth mcp logout

Remove stored OAuth state for a configured MCP server.

Argument	Type	Description
--server	SERVER	Configured MCP server name. Required.
--yes	flag	Confirm logout without prompting.

polytoken auth provider

Manage authentication for a configured provider. A provider with providers.<name>.enabled: false is not visible to these commands; re-enable the provider first.

polytoken auth provider login

Log in to a configured provider with its interactive auth flow.

Argument	Type	Description
--provider	PROVIDER	Configured provider name. Required.
--force	flag	Overwrite existing valid auth state without prompting.
--authorization-code	flag	Use the browser OAuth authorization-code flow instead of the device flow (Codex providers only).

polytoken auth provider status

Show stored auth state for a configured provider, or for every configured provider that uses managed auth when —provider is omitted.

Argument	Type	Description
--provider	PROVIDER	Configured provider name. Omit to show every configured provider that uses managed auth.

polytoken auth provider refresh

Refresh stored auth state for a configured provider.

Argument	Type	Description
--provider	PROVIDER	Configured provider name. Required.

polytoken auth provider logout

Remove stored auth state for a configured provider.

Argument	Type	Description
--provider	PROVIDER	Configured provider name. Required.
--yes	flag	Confirm logout without prompting.

polytoken print

Print machine-readable Polytoken metadata.

polytoken print commands

Print structured CLI command metadata to stdout.

Argument	Type	Description
--format	json, json-pretty, yaml	Output format. Default: json-pretty. Alias: --formats.

polytoken print tools

Print structured tool documentation metadata to stdout.

Argument	Type	Description
--format	json, json-pretty, yaml	Output format. Default: json-pretty. Alias: --formats.

polytoken print lsp-servers

Print the built-in language-server catalog to stdout, in catalog (precedence) order. Pure catalog data: no config loading, no PATH probing.

Argument	Type	Description
--format	json, json-pretty, yaml	Output format. Default: json-pretty. Alias: --formats.

polytoken print slash-commands

Print structured slash-command documentation metadata to stdout.

Argument	Type	Description
--format	json, json-pretty, yaml	Output format. Default: json-pretty. Alias: --formats.

polytoken print tui-command-actions

Print structured TUI keyboard command-action metadata to stdout.

Argument	Type	Description
--format	json, json-pretty, yaml	Output format. Default: json-pretty. Alias: --formats.

polytoken print openapi

Print the daemon’s OpenAPI specification to stdout.

Argument	Type	Description
--format	json, json-pretty, yaml	Output format. Default: json-pretty. Alias: --formats.

polytoken print event-schema

Print the JSON Schema for the DaemonEvent wire envelope to stdout.

Argument	Type	Description
--format	json, json-pretty, yaml	Output format. Default: json-pretty. Alias: --formats.

polytoken print sync-event-schema

Print the JSON Schema for the daemon sync-event wire envelope to stdout.

Argument	Type	Description
--format	json, json-pretty, yaml	Output format. Default: json-pretty. Alias: --formats.

polytoken print fleet-event-schema

Print the JSON Schema for the Outpost fleet-event wire union to stdout.

Argument	Type	Description
--format	json, json-pretty, yaml	Output format. Default: json-pretty. Alias: --formats.

polytoken print outpost-openapi

Print the Outpost OpenAPI specification to stdout.

Argument	Type	Description
--format	json, json-pretty, yaml	Output format. Default: json-pretty. Alias: --formats.

polytoken print schema

Print an authored JSON Schema to stdout.

Argument	Type	Description
<SCHEMA>	app-config, agents-frontmatter, facet-frontmatter, subagent-frontmatter, skill-frontmatter, permissions-config	Required.
--format	json, json-pretty, yaml	Output format. Default: json-pretty. Alias: --formats.

polytoken daemon

Run the daemon in the foreground (not forked).

Argument	Type	Description
--listen	LISTEN	Default: 127.0.0.1:0.
--sessions-dir	SESSIONS_DIR
--log-dir	LOG_DIR
--project-dir	PROJECT_PATH	Required.
--session-id	SESSION_ID
--parent-session-id	PARENT_SESSION_ID
--listener-fd	LISTENER_FD
--global-config-dir	GLOBAL_CONFIG	Global config directory.
--project-config-dir	PROJECT_CONFIG	Project-level config directory.
--todo-dir	TODO_DIR	Override where todo records are read from and written to.
--resume	flag	Resume an existing session from saved history. Requires --session-id.
--credential-file	CREDENTIAL_FILE	Path to the daemon credential file. The CLI generates a credential file at startup and passes this path to the daemon. Required.
--auth-dir	AUTH_DIR	Override the auth directory. When set, the daemon resolves Codex device auth and MCP OAuth credentials from this directory instead of the default data_root()/auth/.

polytoken exec

Run a single non-interactive prompt, print the final result, and write stable exec: ... progress lines to stderr during provider retry waits.

Argument	Type	Description
<PROMPT>	PROMPT	Prompt text. If stdin is piped, stdin content is appended.
--model	MODEL	Override the configured default model for this invocation.
--facet	FACET	Override the exec facet for this invocation.
--max-tool-turns	MAX_TOOL_TURNS	Override the maximum number of tool turns for this invocation.
--output-schema	OUTPUT_SCHEMA	JSON Schema file the exec completion tool must capture before the run finishes. Without it, every exec run still ends by calling the exec_structured_output tool, which captures a default {“output”: string} payload; the captured string is printed raw as the run’s stdout.
--todo-dir	TODO_DIR	Override where todo records are read from and written to.
--print-session-logs	flag	Mirror session id, JSONL session events, and exec trace logs to stderr.

polytoken models

List configured models and selectable reasoning variants.

Argument	Type	Description
--format	human, json, json-pretty, yaml	Output format. Default: human.

polytoken new

Spawn a new daemon session and attach the TUI.

Argument	Type	Description
--sessions-dir	SESSIONS_DIR	Override the sessions registry directory. Useful for tests and for supervisors that want a non-XDG location.
--log-dir	LOG_DIR	Override the log directory.
--no-attach	flag	Spawn the daemon and print its session id and port without attaching.
--prompt	PROMPT	Immediately submit this text as the session’s first prompt. With the TUI (default), the prompt is submitted after the TUI attaches. With —no-attach, the prompt is submitted via HTTP after the daemon is healthy so the agent starts working in the background.
--model	MODEL	Override the configured default model for this session. Accepts a model name exactly as exec --model does: short names and fully qualified strings like model(reasoning). An unknown model fails the command. A facet that pins a model takes precedence over this value.
--facet	FACET	Override the session’s startup facet. An unknown facet fails the command. A facet that pins a model takes precedence over --model.
--adventurously-auto-approve-plan	flag	Start the session with adventurous auto-handoff enabled, as if /adventurously-auto-approve-plan had been run. Takes effect while the session is in the plan facet.

polytoken attach

Attach the TUI to a live session.

Argument	Type	Description
<SESSION_ID>	SESSION_ID	Required.
--sessions-dir	SESSIONS_DIR	Override the sessions registry directory. Useful for tests and for supervisors that want a non-XDG location.

polytoken sessions

List live sessions (stale-cleans any dead entries as a side effect). Pass —all to list every session stored on disk, including historical and legacy sessions.

Argument	Type	Description
--sessions-dir	SESSIONS_DIR	Override the sessions registry directory.
--all	flag	List all sessions from disk (live, historical, and legacy) instead of only live ones. Read-only: skips stale registry cleanup.
--format	human, json, json-pretty, yaml	Output format. Default: human.

polytoken reap

Kill unattached local session daemons.

Argument	Type	Description
<SESSION_ID>	SESSION_ID	Reap exactly this session without checking TUI attachment.
--force	flag	Skip confirmation.
--sessions-dir	SESSIONS_DIR	Override the sessions registry directory.

polytoken continue

Resume a previous session from history.

Argument	Type	Description
<SESSION_ID>	SESSION_ID	Session ID to resume directly, skipping the picker.
--sessions-dir	SESSIONS_DIR
--log-dir	LOG_DIR

polytoken export-session

Export a retained local session as standalone HTML without loading configuration or contacting a daemon.

Argument	Type	Description
<SESSION_ID>	SESSION_ID	Retained session identifier to export. Required.
--output-file	OUTPUT_FILE	Output HTML file. Relative paths resolve from the invocation cwd. Required.
--sessions-dir	SESSIONS_DIR	Override the retained sessions directory.
--force	flag	Replace an existing output file atomically.

polytoken doctor

Run startup-readiness checks and report a checklist.

Argument	Type	Description
--format	human, json, json-pretty, yaml	Output format. Default: human.

polytoken vfs

Inspect shipped polytoken:// resources (ls and cat).

polytoken vfs ls

List VFS schemes or entries in a polytoken:// directory.

Argument	Type	Description
<URI>	URI	Optional polytoken:// URI to list. Omit to list available VFS schemes.

polytoken vfs cat

Print the exact contents of a polytoken:// file to stdout.

Argument	Type	Description
<URI>	URI	The polytoken:// URI to read. Required.

polytoken validate

Validate a skill, facet, or subagent definition file.

polytoken validate skill

Validate a skill definition file by name or path.

Argument	Type	Description
<TARGET>	TARGET	Skill/subagent/facet name (resolved via standard discovery) or path to a markdown file. Required.

polytoken validate subagent

Validate a subagent definition file by name or path.

Argument	Type	Description
<TARGET>	TARGET	Skill/subagent/facet name (resolved via standard discovery) or path to a markdown file. Required.

polytoken validate facet

Validate a facet definition file by name or path.

Argument	Type	Description
<TARGET>	TARGET	Skill/subagent/facet name (resolved via standard discovery) or path to a markdown file. Required.

polytoken theme

Inspect discovered themes and the design token catalog.

polytoken theme list

List discovered theme files (built-in and user).

Argument	Type	Description
--format	human, json	Output format. Default: human.

polytoken theme tokens

List the design token catalog with metadata and default resolved styles.

Argument	Type	Description
--format	human, json	Output format. Default: human.

polytoken theme validate

Validate theme files, reporting errors and warnings.

Argument	Type	Description
--all	flag	Validate all discovered themes instead of one file.
<PATH>	PATH	Theme file path or polytoken:// URI to validate. When omitted (and --all is not set), validates the built-in default.

polytoken lsp

Inspect language-server support.

polytoken lsp check

Check which language servers are installed.

Argument	Type	Description
<NAME>	NAME	Server id to check (e.g. gopls). Omit to list every server.
--format	human, json, json-pretty	Output format. JSON renders the full listing as one array and a named check as a single object. Default: human.

polytoken completions

Generate shell completion scripts for bash, zsh, fish, powershell, or elvish.

Argument	Type	Description
<SHELL>	bash, elvish, fish, powershell, zsh	Shell to generate completions for. Required.

polytoken update

Check for and apply Polytoken self-updates.

Argument	Type	Description
--channel	latest, stable	Release channel to track. Defaults to the updates.channel config value, or latest if unset. If Polytoken cannot load the config, Polytoken warns on stderr and uses latest.
--target-version	TARGET_VERSION	Install a specific version instead of the channel latest. Bypasses the newer-than check (allows downgrades).
--check	flag	Check for available updates without applying them.
--format	human, json	Output format. human (default) prints progress messages; json emits structured JSON to stdout. Default: human.