Setup and project commands

These commands prepare a machine and a repository for AxiomCore: create a backend contract source, diagnose prerequisites, sign in to Axiom Cloud, link a directory to a Cloud project, install tools, and run the editor services, REPL and evaluator. This page covers Axiom CLI 0.149.1.

Every command outside the first row, except join, passes the one-time Cloud access check described in the CLI overview.

Cloud accounts and projects are Alpha and require their configured services.

Start a project

axiom init

Create an axiom.acore backend contract source for an existing FastAPI or Go service. With both an entrypoint and --module, it writes the file directly; otherwise it opens a short terminal wizard.

axiom init [OPTIONS] [ENTRYPOINT]

init also writes type = "backend" into AxiomDeps.toml, keeping its other settings. It refuses to overwrite an existing axiom.acore. The wizard detects Python (requirements.txt, pyproject.toml, main.py) or Go (go.mod, main.go) and uses the directory name as the project name. Use the arrow keys and Enter; Esc or Ctrl+C leaves, and q closes the success screen. Building the contract needs the extractor described in Install the Axiom CLI.

axiom init main.py:app --module axiom-fastapi

axiom onboard

Detect the repository's role and print the shortest supported first path. Run it from the application root before you create files.

axiom onboard [OPTIONS]

A backend is detected from axiom.acore, main.py, app.py, pyproject.toml, go.mod or main.go; a frontend from package.json, pubspec.yaml or AxiomDeps.toml; both give fullstack. onboard does not log in, release or pull unless you supply the option that needs it. --apply only creates axiom.acore and refuses to overwrite one.

Releasing is always a separate, explicit step:

axiom build
axiom login
axiom build --release --out backend.axiom

axiom doctor

Inspect local prerequisites without changing files, logging in or pulling a contract. It is safe in a new checkout and in CI.

axiom doctor [OPTIONS]

Each check has an id, a status (pass, warn or fail), a summary, a detail and, when available, a fix with the next command. Failures are missing prerequisites such as an invalid AxiomDeps.toml, an unreadable artifact or a missing tool.

axiom doctor --json --strict > axiom-doctor.json

{
  "schema_version": 1,
  "control_plane": "https://api.axiomcore.dev",
  "project_root": "/path/to/app",
  "checks": [{ "id": "cli", "status": "pass", "summary": "Axiom CLI 0.149.1 is available", "detail": "The current executable is running normally.", "fix": null }]
}

The report never includes tokens, keys or contract contents, but project_root is a local path: review it before you share a report publicly.

Sign in to Axiom Cloud

axiom login

Sign in to Axiom Cloud with the device authorization flow. The terminal shows a code and a URL, then waits until you approve the code in the browser.

axiom login

No options other than --help.

The session is saved in the CLI profile directory (see the CLI overview). Browser sign-in and CLI device login are separate sessions. In automation, authenticate through the supported environment and pass explicit project and version options instead of relying on terminal selection.

axiom join

Join the Axiom Cloud waitlist when you do not have a referral code.

axiom join <EMAIL>

join only adds the address to the waitlist. The referral code itself is asked for once, by the first command that uses Axiom Cloud, or read from AXIOM_REFERRAL_CODE. Local commands work without joining.

Link Cloud projects

axiom project

Manage Axiom Cloud projects and local Acore project packages.

axiom project <COMMAND>

Project operations need authentication, project membership and a reachable control plane. A directory link is stored in your CLI profile, not in the repository.

axiom project list

List the Cloud projects you can access, by name and slug.

axiom project list

No options other than --help.

axiom project create

Create a Cloud project and link the current directory to it.

axiom project create [OPTIONS]

In 0.149.1 the command always needs an interactive terminal, even when you pass every option: it fails without one or when CI is set. It prompts for any missing value, then links the current directory. In automation, create the project once interactively or in the Cloud Dashboard, then use axiom project link --project-id.

axiom project create --name "Payments API" --slug payments-api

axiom project link

Link the current directory to a Cloud project, so release and other Cloud commands find it without --project.

axiom project link [OPTIONS]

axiom project link --project-id payments-api

axiom project rotate-key

Replace the project's active signing key. Old public keys stay available, so earlier releases still verify.

axiom project rotate-key --project <PROJECT>

axiom project resolve

Resolve the dependencies of a local Acore project and write a lock file. Use it for an Acore project that declares package dependencies in a PklProject file.

axiom project resolve <DIR>

The command reads the dependencies URIs, selects the minimum compatible versions, fetches each package's metadata over the network and writes PklProject.deps.json. If metadata cannot be fetched, it prints a warning and records the dependency without checksum verification: review the lock file.

axiom project package

Package a local Acore project.

axiom project package <DIR>

Install tools and manage the cache

axiom install

Install the bundled language server, an intact .axiomapp application, or a compiler or extractor module.

axiom install [OPTIONS] <PACKAGE>

The language server installer copies the current host's executable only; it cannot create a server for another OS or CPU. It does not edit editor settings or PATH. Run it again after you update the CLI, then restart the editor's language server. It is validated on Apple Silicon macOS; Linux, Windows and Intel macOS acceptance is pending.

axiom install lsp-server
~/.axiom/bin/acore-lsp --version-json
axiom install dist/my-app-web.axiomapp

axiom cache

Inspect or clear the CLI profile's local cache. These commands do not clear Flutter application or browser session caches.

axiom cache <COMMAND>

The cache lives in the cache/ folder of the CLI profile directory. Cached payloads can contain application data: redact them before you paste output into an issue or support channel.

axiom cache ls

List cache entries in a terminal interface. Use j/k or the arrow keys to move, x to delete the selected entry, and q or Esc to exit.

axiom cache ls

No options other than --help.

axiom cache get

Print one cache entry: timestamps, TTL, headers, payload size, and the JSON or byte payload.

axiom cache get --key <KEY>

axiom cache clear

Delete every entry in the CLI cache and print how many were removed.

axiom cache clear

No options other than --help.

Editor services

axiom lsp

Run the Acore language server over stdin and stdout, without Cloud access. Point an editor at axiom lsp, or install a standalone copy with axiom install lsp-server.

axiom lsp [OPTIONS]

axiom lsp --version

acore-lsp 0.1.4 (axiom-editor/v1)

--version-json prints compilerVersion, protocolVersion and serverVersion (for example acore/0.1.4 (CLI 0.149.1)). The installed acore-lsp executable accepts the same two flags.

No Acore editor extension is published in an extension registry yet. Where you use the Acore editor adapters, configure them with an absolute path (~ is not a portable editor setting; on Windows include .exe and use forward slashes or escaped backslashes):

{
  "lsp": {
    "acore-lsp": {
      "binary": { "path": "/path/to/acore-lsp" }
    }
  }
}

axiom editor

Offline saved-source checking and editor compatibility metadata. Editor integrations call these commands; you can also run them to reproduce what an editor reports.

axiom editor <COMMAND>

check, report and refresh-extraction share these inputs:

axiom editor info

Print the CLI version, editor protocol, saved-check format and compiler identity. Editors use it to confirm compatibility.

axiom editor info [OPTIONS]

Axiom 0.149.1 · axiom-editor/v1 · axiom-editor-check/v1

axiom editor check

Check saved source and manifests statically with the owning compiler. It writes no artifacts and exits non-zero when the check fails.

axiom editor check [OPTIONS] --entry <ENTRY> --root <ROOT> --kind <KIND>

axiom editor check --entry main.acore --root . --kind backend

Saved static check: main.acore · backend/v1 · default

axiom editor report

Print a read-only report of saved private inputs and the semantic graph. No provider is contacted. The output is axiom-editor-report/v1 JSON.

axiom editor report [OPTIONS] --entry <ENTRY> --root <ROOT> --kind <KIND>

axiom editor refresh-extraction

Run the declared native extractors explicitly and store the fenced extraction cache, so later saved checks can read extracted interfaces.

axiom editor refresh-extraction [OPTIONS] --entry <ENTRY> --root <ROOT> --kind <KIND>

This command runs extractor code, unlike the other editor commands.

axiom editor workflows

Describe the explicit editor tasks that this CLI accepts, generated from its real argument definitions: each workflow's ID, command and typed inputs.

axiom editor workflows [OPTIONS]

axiom editor validate-workflow

Validate a typed workflow request against the catalog and parse the command line it would run, without executing it.

axiom editor validate-workflow --request <REQUEST> --root <ROOT>

axiom editor validate-workflow --root . \
  --request '{"workflow":"check","inputs":{"file":"axiom.acore","json":true}}'

The result is axiom-editor-workflow-validation/v1 JSON with the resolved argv and "execution": false.

Explore Acore

axiom repl

Start the Acore REPL. Type an expression to evaluate it, and exit or quit to leave.

axiom repl

No options other than --help.

axiom eval

Evaluate an Acore file and print its output. Use it to see the rendered value of any Acore module, contract or not.

axiom eval [OPTIONS] <FILE>

axiom eval main.acore --format json