CLI Commands Reference

The anyy command opens the TUI when run without a subcommand. Its public commands configure and operate the selected Profile and resident Gateway.

Global Entry Point

anyy [--profile NAME] [--profile-root PATH] [--role ROLE]
anyy [--profile NAME] [--profile-root PATH] [--role ROLE] COMMAND
anyy --version
anyy --resume SESSION_ID

Invocation selectors such as --profile, --profile-root, --role, and --no-color appear before the command. For the default TUI, --home, --socket, and --resume follow anyy directly. With a subcommand, put its supported --home/--socket flags after that subcommand; placing these before it is rejected.

Flag	Purpose
--profile NAME	Select a named Profile
--profile-root PATH	Override the Profile manager's base root
--role ROLE	Select the initial Role for a new conversation
--resume ID	Open a known session in the TUI
--home PATH	Select TUI Home, or override Home after a command that accepts it
--socket PATH	Select TUI socket, or override socket after a command that accepts it
--no-color	Disable colored terminal output
--version	Print version information

Use anyy COMMAND --help for the exact flags supported by the installed version.

Chat and Health

anyy / --resume

anyy
anyy --resume SESSION_ID

Open the Terminal Interface, optionally resuming one session.

anyy chat

anyy chat [--home PATH] [--socket PATH] [--role ROLE] \
  [--session ID] [--json] PROMPT

Send one new prompt through an already running resident Gateway. --session selects an existing conversation for that prompt; if it is busy, the input joins its follow-up queue. --json returns a structured result. Enabled tools execute directly. Use anyy --resume ID to open an existing conversation in the TUI; see Sessions for queue controls.

A successful JSON response contains:

Field	Meaning
session_id	Conversation receiving the input
submission_id	Original accepted input whose result was awaited
execution_id	Reusable Session lane
agent_run_id	Actual run supplying the answer
execution_state	Observed lane state; normally idle after completion
outcome	That invocation's outcome; succeeded is success
stop_reason	Completion or failure classification
assistant_text	Visible answer from the recorded result messages for that run

An idle lane alone is not success. Clarification (suspended), failure, interruption, cleared input and timeout exit nonzero without printing an intermediate assistant answer. Timeout or caller cancellation stops observation only. The command keeps the original submission identity and never substitutes the latest Session messages. See CLI Interface.

Conversation tool selection

The CLI accepts these flags for the default TUI and chat. They select tools for the addressed Session; they do not change Gateway or Profile defaults.

Flag	Meaning
--tools LIST, -t LIST	Comma-separated names/patterns, or a list of exact +name/-name modifiers to the default selection
--exclude-tools LIST, -xt LIST	Comma-separated names/patterns to exclude
--no-tools, -nt	Start with all default tool activation suppressed
--no-builtin-tools, -nbt	Suppress default built-in activation while keeping extension defaults

anyy --tools '+codemode,+tool_search'
anyy chat --tools 'read,bash' --exclude-tools 'bash' "Inspect this project"
anyy chat --session SESSION_ID --tools '' "Answer without tools"

Plain patterns support *. A modifier list cannot mix plain names with modifiers or use wildcard modifiers. An empty --tools '' is an explicit empty allowlist; an empty --exclude-tools '' clears that exclusion override. Put flags before the prompt. They may precede chat or follow it; a command-local list replaces the corresponding global list. These flags are rejected for administration commands.

The two suppression flags are separate Go boolean flags. Use --no-builtin-tools for the built-in case; Pi's --no-tools builtin syntax is not supported. --no-tools takes precedence when both are present. Codemode's on/only mode is a Profile setting, with no --codemode-mode flag.

A new Session receives tool_selection through session.new. Explicit flags on an existing Session invoke session.tools.configure first; active work, queued input, pending admission or summary work returns a conflict and no new chat input is submitted. With no override, attaching to a hot Session keeps its current active names. Cold raw restoration and branch navigation use the selected branch's canonical declarations; they differ from SDK-style explicit initial selection.

See Sessions for tool restoration, resource reload and current Session settings.

Local prompt diagnostic

anyy prompt eval local --authorize-live

Make real, potentially billable calls to the active Profile's model in an isolated temporary session. The command prints responses and actual usage and latency, and writes a private report. --home PATH selects the Profile; --output PATH chooses the report's write-once path. Keep terminal output and the report private. This diagnostic does not start channels or cron and does not grade model quality or certify Pi alignment.

anyy status

anyy status [--home PATH] [--socket PATH] [--json]

Report selected Profile/Gateway/runtime status.

anyy doctor

anyy doctor [--home PATH] [--config PATH] [--json]

Run configuration and runtime diagnostics.

anyy config

anyy config [--home PATH] [--config PATH]

Show the configuration dashboard in the terminal: paths, provider/model, endpoint, and credential-reference status. This command does not edit configuration or reveal secret values.

Setup and Models

anyy setup

anyy setup [--home PATH]
anyy setup model [--home PATH]
anyy setup model fallback [--home PATH]
anyy setup channel [--home PATH]
anyy setup channel CHANNEL [--home PATH] \
  [--set INPUT=VALUE] [--sensitive-fd INPUT=FD] \
  [--external-locator-fd INPUT=FD]

Run the interactive full/quick setup or a focused model/channel flow. See Setup.

anyy tools

anyy tools [--home PATH] [--probe]
anyy tools list [--home PATH]
anyy tools websearch [--home PATH]
anyy tools image [--home PATH] [--probe]
anyy tools image understanding [--home PATH] [--probe]
anyy tools image generation [--home PATH] [--probe]
anyy tools video [understanding] [--home PATH] [--probe]
anyy tools voice [--home PATH] [--probe]
anyy tools voice tts [--home PATH] [--probe]
anyy tools voice stt [--home PATH] [--probe]

Configure optional web, image, video, and voice capability backends.

Gateway and Dashboard

anyy gateway

anyy gateway start [--home PATH]
anyy gateway restart [--home PATH]
anyy gateway status [--home PATH]
anyy gateway stop [--home PATH]

Manage the resident Gateway background service.

anyy dashboard

anyy dashboard [--home PATH] [--socket PATH] [--listen ADDR] [--no-open]
anyy dashboard --status
anyy dashboard --stop

Start, inspect, or stop the on-demand Dashboard sidecar. See Dashboard Overview.

Messaging

anyy channel

anyy channel doctor CHANNEL [--home PATH] [--socket PATH] [--json]
anyy channel pairing list [--channel CHANNEL] [--account ACCOUNT] [--all] [--json]
anyy channel pairing approve --request REQUEST
anyy channel pairing approve --prompt-code --channel CHANNEL --account ACCOUNT
anyy channel pairing approve --code-stdin --channel CHANNEL --account ACCOUNT
anyy channel pairing reject --request REQUEST
anyy channel pairing revoke --grant GRANT [--reason TEXT]
anyy channel reload [--home PATH] [--socket PATH] [--json]

Diagnose Channels, decide pairing requests, revoke grants, and reload runtime configuration. See Messaging Platforms.

Skills and MCP

anyy skills

anyy skills list [--home PATH] [--json]
anyy skills view [--home PATH] [--json] NAME [FILE_PATH]
anyy skills install [--home PATH] [--socket PATH] [--name NAME] [--force] [--now] [--json] ZIP_PATH
anyy skills uninstall [--home PATH] [--socket PATH] [--now] [--json] NAME
anyy skills rollback [--home PATH] [--socket PATH] [--revision REVISION_ID] [--now] [--json] NAME
anyy skills reload [--home PATH] [--socket PATH] [--json]

Inspect, install, remove, roll back, and reload Skills.

anyy mcp

anyy mcp add SERVER_ID [--home PATH] --transport stdio --command CMD [--cwd DIR] [--env KEY=VALUE] [--disable] [--args ARG...]
anyy mcp add SERVER_ID [--home PATH] --command CMD [--cwd DIR] [--exposure codemode|deferred|direct|hidden] [--tool-exposure JSON] [--description TEXT] [--args ARG...]
anyy mcp add SERVER_ID [--home PATH] --url URL [--transport http] [--auth JSON] [--oauth JSON] [--header KEY=VALUE] [--exposure codemode|deferred|direct|hidden]
anyy mcp add SERVER_ID [--home PATH] --preset filesystem [-- ARG...]
anyy mcp add SERVER_ID [--home PATH] --local --url URL [--oauth JSON] [--header KEY=VALUE]
anyy mcp add SERVER_ID [--home PATH] --local --command CMD [--cwd DIR] [--env KEY=VALUE] [--args ARG...]
anyy mcp configure SERVER_ID [--home PATH] [--socket PATH] [--exposure codemode|deferred|direct|hidden] [--enable]
anyy mcp configure SERVER_ID [--home PATH] [--socket PATH] [--tool-exposure JSON] [--description TEXT]
anyy mcp login SERVER_ID [--home PATH] [--socket PATH] [--timeout SECONDS] [--json]
anyy mcp logout SERVER_ID [--home PATH] [--socket PATH] [--json]
anyy mcp remove SERVER_ID [--home PATH] [--force]
anyy mcp remove SERVER_ID [--home PATH] --local
anyy mcp enable SERVER_ID [--home PATH] [--project]
anyy mcp disable SERVER_ID [--home PATH] [--project]
anyy mcp set SERVER_ID KEY VALUE [--home PATH]
anyy mcp unset SERVER_ID KEY [--home PATH]
anyy mcp status [--home PATH] [--socket PATH] [--json]
anyy mcp list [--home PATH] [--socket PATH] [--json]
anyy mcp call SERVER.TOOL [--args JSON] [--home PATH] [--socket PATH] [--json]
anyy mcp call SERVER_ID TOOL_NAME [--args JSON] [--home PATH] [--socket PATH] [--json]
anyy mcp show SERVER_ID [--home PATH] [--socket PATH] [--json]
anyy mcp probe SERVER_ID [--home PATH] [--socket PATH] [--json]
anyy mcp test SERVER_ID [--home PATH] [--socket PATH]
anyy mcp reload [SERVER_ID] [--home PATH] [--socket PATH] [--json]
anyy mcp logs [SERVER_ID] [--home PATH] [--socket PATH] [--json]
anyy mcp serve [--home PATH] [--socket PATH]

Manage stdio or HTTP MCP servers, authentication, exposed tools, runtime status, and direct calls. Run anyy mcp --help before adding a server; transport flags differ.

add saves an enabled lazy server by default; --disable turns it off. Configuration uses exposure and ordered overrides without a tool picker or required probe. RPC tool_exposure carries an ordered JSON object string. Probe reports one tools inventory with exposure/offered facts.

configure --exposure/--enable changes settings in the selected source or existing project override. configure --description/--tool-exposure and generic set/unset edit the raw Profile definition. Mixing the two configure domains is rejected; issue separate commands. Inspect the source with show before editing.

add --cwd DIR applies only to stdio servers. Add and generic set SERVER_ID cwd VALUE preserve the supplied relative, absolute or leading-home path; cwd uses the resident canonical Workspace as its relative base.

Ordinary MCP value writes preserve the input string and its expression syntax; a sensitive-looking field name does not trigger automatic Secret storage. Explicit Profile env:, secret: and file: references retain their own resolution rules.

--project applies only to enable/disable of an unoverridden Profile server and writes an enabled-only project override. --local (also -l) applies only to add/remove and writes .anyy/mcp.json in the Profile's canonical Workspace. Local add replaces the named entry without --force; local remove preserves Profile configuration and grants. Neither operation reloads a running entry. Adding or removing MCP server definitions in the Profile configuration keeps its existing confirmation and credential behavior.

reload reconnects loaded configuration without rereading files. Startup or an idle session.reload RPC rereads Profile and project files. Login's --timeout defaults to 300 seconds and limits authorization only. See MCP configuration.

logout removes the selected server's saved local OAuth authorization, including supported client material; it does not delete the server definition. It uses the resident runtime when available, otherwise requires exclusive offline Profile ownership.

anyy mcp serve exposes Anyy to another MCP client. The messages_send result follows the original submission and may report a clarification suspension without claiming a final answer. See the MCP conversation result and await API reference.

Automation

anyy cron

anyy cron list [--home PATH] [--include-disabled] [--role ROLE] [--workspace WORKSPACE] [--all-scopes] [--json]
anyy cron create [--home PATH] --name NAME --schedule SCHEDULE --prompt TEXT \
  [--kind agent|skill|notify] [--skills LIST] [--role ROLE] [--workspace WORKSPACE] \
  [--delivery-target TARGET] [--delivery-channel CHANNEL] [--toolsets LIST] [--json]
anyy cron create [--home PATH] --name NAME --schedule SCHEDULE --kind script --script NAME \
  [--workdir PATH] [--role ROLE] [--workspace WORKSPACE] [--delivery-target TARGET] [--json]
anyy cron update [--home PATH] --id ID [--enable|--disable] [--schedule SCHEDULE] [--prompt TEXT] \
  [--role ROLE] [--workspace WORKSPACE] [--all-scopes] [--json]
anyy cron delete [--home PATH] --id ID [--role ROLE] [--workspace WORKSPACE] [--all-scopes] [--json]

Create agent, skill, script or notification jobs. With no explicit kind, --script selects script; otherwise the default is agent. Agent/skill/notify jobs require --prompt, and script jobs require --script. Delivery targets are gateway, origin, current_user_default or none, subject to the route requirements described in Automations. Scheduled runs retain their saved Role, Workspace, payload and delivery route.

anyy heartbeat

anyy heartbeat status [--home PATH] [--json]

Report resident heartbeat state.

Profiles and Roles

anyy profile

anyy profile list [--json]
anyy profile get NAME [--json]
anyy profile create NAME [--display-name NAME] [--json]
anyy profile use NAME [--json]
anyy profile delete NAME --force [--purge-secrets] [--json]

Manage isolated Profile homes. Delete is destructive and requires --force.

anyy role

anyy role list [--home PATH] [--include-archived] [--json]
anyy role get [--home PATH] ROLE_ID [--json]
anyy role create [--home PATH] ROLE_ID [--display-name NAME] [--json]
anyy role update [--home PATH] ROLE_ID [--display-name NAME] [--soul-file PATH] [--json]
anyy role use [--home PATH] ROLE_ID [--json]
anyy role delete [--home PATH] ROLE_ID [--json]

Inspect and manage assistant Roles and Soul content.

Backup, Maintenance, and Release Lifecycle

anyy backup

anyy backup create [--home PATH] [--output PATH] [--include-secrets] [--json]
anyy backup restore --archive PATH --target-home PATH [--json]
anyy backup list [--home PATH] [--json]

Create, list, or restore Profile backups. --include-secrets additionally includes the managed secrets/ and mcp/oauth/ directories. Configuration and Workspace files can already contain inline credentials without that flag; backup does not redact every included file. Keep every archive private and protect it as sensitive data. See Backup & Restore for the capture boundary and recovery steps.

anyy maintenance

anyy maintenance compact-state [--home PATH] (--output PATH | --replace) [--temp-dir PATH] [--json]
anyy maintenance checkpoint-state [--home PATH] [--json]
anyy maintenance cache-token-estimates [--home PATH] [--limit N] [--execute] [--json]

Perform state-database and token-estimate maintenance. Commands that replace state should be preceded by a verified backup.

anyy update

anyy update [--home PATH] [--version VERSION] [--base-url URL]
anyy update --compact [--home PATH] [--version VERSION] [--base-url URL]
anyy update --check [--home PATH] [--version VERSION] [--base-url URL]

Check or update a native resident installation. See Updating & Uninstalling.

anyy uninstall

anyy uninstall
anyy uninstall --keep-data --yes
anyy uninstall --full --yes
anyy uninstall --home PATH --keep-data --yes

Remove a native resident installation. Choose either --keep-data or --full before using --yes (-y). They cannot be combined. --home PATH selects the installation home; --full also removes all Anyy data in scope, so back up first.