CLI Reference

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

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.

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.

polytoken auth provider status

Show whether a configured provider has stored auth state.

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

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 openapi

Print the daemon’s OpenAPI specification to stdout.

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

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

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

Print authored JSON Schemas to stdout.

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

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.

polytoken exec

Run a single non-interactive prompt and print the final result.

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 that the assistant must capture before exit.
--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.

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

Argument	Type	Description
--sessions-dir	SESSIONS_DIR	Override the sessions registry directory.
--format	human, json, json-pretty, yaml	Output format. Default: human.

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