CLI Reference

axon

Open the TUI with the default agent.

axon

axon --version

Print the installed Axon version.

axon --version

axon --agent

Open a named agent instead of the default:

axon --agent <name>

Regenerates axon.manifest.json, axon.d.ts, and .axon/tools.d.ts before opening.

Authenticate with your Axon account. Required before deploying or publishing.

axon login

Opens a browser to complete authentication. Stores credentials in ~/.axon/auth.json. Run once — subsequent commands use the stored session.

axon logout     # clear stored credentials
axon whoami     # print the currently authenticated account

axon init

Scaffold a new named agent at ~/.axon/agents/<name>/.

axon init <name>

Creates the agent folder with axon.config.ts, tsconfig.json, axon.d.ts, and empty prompts/, scripts/, and server/ directories. Open it with axon --agent <name>.

axon agent

Manage, deploy, and publish agents.

axon agent list                     # list all agents at ~/.axon/agents/
axon agent deploy                   # deploy the agent to Axon's cloud
axon agent publish                  # publish the agent to the registry
axon agent status                   # check the status of the deployed agent
axon agent logs                     # tail live logs from the deployed agent
axon agent undeploy                 # tear down the deployed agent

axon agent deploy

Builds the agent bundle, pushes it to Axon's infrastructure, and returns the agent's public URL and API key. Requires axon login.

axon agent deploy

On first deploy, prints:

Deployed: https://agents.axon.run/you/my-agent
API key:  axon_...

Subsequent deploys update the running agent in place.

axon agent publish

Publishes the agent to the Axon registry so others can install it. Does not deploy a cloud endpoint.

axon agent publish

See Publishing for what is included and excluded from the bundle.

axon agent env

Manage secrets for a deployed agent. Secrets are encrypted and injected into the container at runtime — they are never stored in your agent folder.

axon agent env list             # list configured keys (values never shown)
axon agent env set KEY value    # set a secret
axon agent env unset KEY        # remove a secret

axon agent keys

Manage API keys for a deployed agent.

axon agent keys list            # list API keys
axon agent keys rotate          # rotate the active key (old key stops working)
axon agent keys revoke <id>     # revoke a specific key

axon install / axon uninstall

Install or remove a module from an agent.

axon install <id>                  # install into the active agent
axon install <id> --agent <name>   # install into a specific agent
axon uninstall <id>                # remove an installed module

Flags

Flag	Description
`--agent <name>`	Target a specific agent instead of the active one.

Notes

<id> is the registry identifier: @scope/name or name.
Installing merges the module's prompts, scripts, and tool dependencies into the agent folder. Nested module dependencies are resolved and merged automatically.
If the module declares needs, the CLI prompts for env values and writes them to .env.

axon module

Author and publish modules.

axon module init <name>            # scaffold a new module project in the current directory
axon module publish                # publish the module to the registry

Notes

axon module init creates module.config.ts and empty prompts/, scripts/ directories.
axon module publish must be run from the module project folder. Publishes to the registry and npm simultaneously.
See Publishing a module for what is included and excluded from the bundle.

axon run

Invoke a script from the current agent without opening the TUI.

axon run <script>                  # invoke a script by name
axon run <script> --key value      # invoke with named arguments

Notes

Boots the agent, runs the script, then exits. No TUI is opened.
Script names match the filename without extension: scripts/close-plan.ts → axon run close-plan.
Arguments are passed as named flags and available via args / defineArgs<{}>() inside the script.
Useful for automation: cron jobs, CI steps, git hooks.

axon run close-plan --issueId bd-yiq
axon run sprint-close

axon prepare

Regenerate axon.manifest.json, axon.d.ts, and .axon/tools.d.ts for the current agent.

axon prepare

axon.manifest.json is the agent's module manifest. axon.d.ts declares the auto-injected globals. .axon/tools.d.ts contains tool type declarations for all installed modules — what makes axon.tools.* calls fully typed.

Run this after installing or removing modules if you want updated types without reopening Axon. Runs automatically on open — explicit use is only needed for mid-session type refreshes.