CLI

axon is how you drive Axon from a shell — scaffolding projects, running agents, generating types, and putting things in the cloud. It is one binary and it reads the directory you are standing in, so most commands take no arguments.

axon                    # open the terminal on your default agent
axon --help             # every command, one line each
axon --version

With no arguments it opens the Terminal. Everything below is what you do without it.

A day with an agent

Five commands cover most of them:

axon init my-agent      # scaffold — a real agent, not a stub
cd my-agent
axon dev                # boot it, watching for changes
axon . -p "summarise the open issues"
axon deploy             # put it in the cloud

init installs dependencies and generates types, so the folder is ready to edit immediately. dev boots it as a local server that hot-reloads on save. A bare reference (., @scope/name, a path) plus -p is one execution and out — an agent and something to do, both named rather than inferred, which is what makes it safe in cron and CI. The answer goes to stdout and everything else to stderr, so a pipe or a redirect gets only the answer. deploy ships the same folder, unchanged.

Or hand it off

axon . -p "…" waits with you. When you would rather not wait, delegate it:

axon job create -c "summarise the open issues"
axon job list                                   # what came back
axon job done 9c533cee                          # you are satisfied with it

job hands work to an agent and keeps the record of what happened. It runs without you, survives the terminal closing, and asks when it needs something only you can answer. The agent reports what it did; whether that is what you wanted stays your call.

One grammar, five kinds

Agents are not the only thing you build. Modules, cognets, benches, prompts and terminal extensions are all projects, and they all take the same three verbs:

axon module init my-tool     # or cognet | bench | prompt | ext
cd my-tool
axon prepare                 # regenerate its types
axon publish                 # push it to the registry

Agents are the default kind, which is why they alone need no noun in the middle.

The bare verbs read your directory. axon prepare and axon publish detect what kind of project you are in and do the right thing — there is no axon module prepare to remember, though the explicit form exists for acting from elsewhere. prepare installs declared modules, compiles the cognet and regenerates the authoring types; run it after changing modules, tools or prompts and your editor catches up with the agent.

The registry

axon search obsidian --modules
axon search --kind cognet --limit 5

axon install @axon/github       # into the current agent
axon clone @axon/github         # a copy you can edit

search takes the filters — --kind, --scope, --sort, --limit. A query is optional, so it browses as well as searches.

The other two differ in what you end up owning: install adds a capability to the agent you are in, and clone copies an artifact out as an editable project. See Installing.

Deployments

axon deploy             # from the agent folder

An omitted target means the agent in your current directory. bundle produces the image without deploying it, which is the path to running Axon on your own infrastructure.

Your account

axon login              # required before deploy or publish
axon whoami
axon logout
axon update             # update the CLI itself

Credentials live in ~/.axon/auth.json.

Scripting it

--json makes any command print one line of JSON to stdout and nothing else, which is what makes the CLI usable from another program:

axon search --kind cognet --json

Two things worth reading once

what prepare actually generates for each kind.

Installing — how install and clone differ, and what each does to your project.

Between them they make the rest of the command list inferable rather than memorised.

For the same operations without leaving the terminal, see Terminal. For what you write inside an agent, see the SDK.