Build and run commands

These commands take Acore source to a checked contract, a running local service or application, a generated client, or a Cloud release. This page covers check, build, run, serve, watch, explain, diff, pull, package, release, deploy, migrate and benchmark in Axiom CLI 0.149.1.

Diagram source

flowchart LR
  S[.acore source] --> C[axiom check]
  C --> B[axiom build]
  B --> A[.axiom contract]
  S --> R[axiom run or axiom serve]
  A --> P[axiom pull]
  P --> G[Generated client]
  A --> RL[axiom release]
  RL --> CL[Axiom Cloud]
  U[axiom ui build] --> PK[axiom package]
  PK --> R

check validates source and build writes a .axiom contract. run and serve execute source locally without building first. pull turns a contract into a client for your framework, and release uploads a backend contract to Axiom Cloud. Application artifacts (.axiomapp) come from axiom ui build; package combines them and run opens them.

Check and build contracts

check and build select the frontend, backend or database compiler from the nearest AxiomDeps.toml and its type field. Legacy sources without a declared type keep their profile or module selection. Options that belong to another contract type fail with a clear error.

axiom check

Check a frontend, backend or database contract without writing project outputs. Use it before every build and as a CI gate.

axiom check [OPTIONS] [FILE]

check prints diagnostics and exits non-zero on an error. The JSON report has valid, profile, variant, file and diagnostics. It leaves source, artifacts, project locks and diff baselines untouched, does not need Cloud login, and does not resolve or download frontend dependencies: prepare the locks first.

axiom check main.acore --json

{"diagnostics":[],"file":"main.acore","format":"axiom-contract-check/v1","profile":"backend","valid":true,"variant":"default"}

axiom build

Build a contract under the owning project's .axiom/contracts/ directory, or export it to a path you choose with --out.

axiom build [OPTIONS] [FILE]

Default outputs, wherever you run the command from:

With --out, the backend plan is written beside the output, for example dist/hello.axiom and dist/hello.server.json. Use an explicit export path when you distribute a schema package.

--frozen-interface compares the public interface before replacing outputs. An inferred new failure, type or projection needs an explicitly reviewed baseline update. This check is separate from FlatBuffers slot compatibility. Frontend snapshots and database packages cannot use the backend Cloud release path: to run frontend source use axiom run, and to create an installable application use axiom ui build.

axiom build frontend/main.acore
axiom build backend/axiom.acore
axiom build database/schema.acore --out dist/schema.axiom
axiom build axiom.acore --release --project my-project --version 1.2.1

axiom explain

Print the expanded backend contract JSON, or the machine-readable catalog of backend declarations. Use it to see exactly what the compiler produced.

axiom explain [OPTIONS] [FILE]

axiom explain axiom.acore --provenance
axiom explain --schema

Run locally

axiom run

Run a backend, a frontend, a database SQL console or a packaged .axiomapp. The CLI picks the behavior from the input and builds stale local contracts as needed.

axiom run [OPTIONS] <SOURCE>

Options for another input kind are rejected. For example --target, --lock, --frozen, --once and --launch fail for a backend, and the backend options fail for a frontend or .axiomapp. A database run rejects --target, --mode, --launch and --watch; use axiom database status --watch to monitor.

Backend. --watch needs source-owned managed or sandbox plans and a fixed loopback port; external services use their own reload tooling. Missing executable configuration fails. Native action symbols need a registered application host, and Python or Go services need their server adapter (see axiom server boundary). With declared storage, the CLI compiles the private plan and bindings itself. Send the printed development key in the apikey header. The key is stored in .axiom/database/development.key; keep it local.

Database console. The console accepts SQL plus \dt, \d TABLE, \conninfo and \q. Ctrl+C cancels the current input or query and Ctrl+D exits.

axiom run backend/main.acore --database-url "$DATABASE_URL"
axiom run frontend/main.acore --target web --port 5173 --launch
axiom run database/schema.acore --database-file ./tasks.sqlite --no-shell --execute 'SELECT count(*) FROM tasks'
axiom run dist/my-app-web.axiomapp --target web

axiom serve

Start the real local API. serve never falls back to mocks or to Cloud.

axiom serve [OPTIONS] [INPUT]

Managed and sandbox serving needs reviewed configuration. With --mock, the full simulation keeps action guards and supported transport enforcement, uses no production bodies or providers, and rejects --deployment, --bindings and --delivery. Input files must be regular files no larger than 16 MiB. Provider values that a deployment references by environment variable name are read from the environment.

axiom serve axiom.acore --watch --port 8080
axiom serve backend.axiom --plan backend.server.json --deployment deployment.json
axiom serve axiom.acore --mock --fixtures mock.json --identities mock-identities.json

axiom watch

Watch for changes and rebuild or pull automatically. The watch display is a terminal interface: press q (or Esc with --build) to stop, and r to refresh with --build.

axiom watch [OPTIONS]

With --build, the command watches axiom.acore, the FastAPI or Go entrypoint file named in its amends line, and the source path its manifest declares. It shows rebuild state, the last synchronization time and semantic changes. It is not a recursive, framework-independent development server: confirm that your extractor entrypoint is among the watched paths, and use explicit build and test commands in CI. Without axiom.acore in the current directory it prints a notice and exits.

Without --build, the command first runs axiom pull with the current dependency configuration, then watches project.axiom in the current directory for contract changes.

Compare and migrate source

axiom diff

Show what changed between two Acore files, or between a file and the baseline that axiom build recorded.

axiom diff [OPTIONS] <FILE1> [FILE2]

diff reports changes and exits 0. It does not fail on breaking changes; use axiom inspect diff --fail-on for a CI gate. Without a baseline it tells you to run axiom build FILE first.

axiom diff main.acore v2.acore --format semantic

Semantic State Changes:

+ $.models.Greeting.fields.note = {"isOptional":true,"name":"note","typeRef":{"kind":"strin...

axiom migrate

Convert a legacy backend contract into a new sibling source that uses the backend profile. The original source is preserved.

axiom migrate --output <OUTPUT> <FILE>

The command writes the new source only when every variant preserves its evaluated JSON. It also writes an identity sidecar that keeps endpoint IDs stable, and sets type = "backend" in AxiomDeps.toml. It refuses an existing output or sidecar, and a source that already uses the backend profile.

axiom migrate axiom.acore --output service.acore

Clients, packages and releases

axiom pull

Fetch a contract and generate a typed client for your framework. Use it in a frontend project that consumes a backend contract.

axiom pull [OPTIONS] [SOURCE]

pull fetches every contract before it writes AxiomDeps.toml, so a failed lookup does not leave an unusable dependency. Remote references need network and are authorized by the service; a local artifact does not. Do not infer from an anonymous not found whether a private project exists. Flutter generation needs Flutter. Web generation (atmx-web, atmx-react) needs Node.js and npm and runs the project's node_modules/.bin/atmx. Install the published generator first with npm install --save-dev atmx-cli@0.146.7: without a local copy, the CLI runs npx atmx-cli@<CLI version>, and no atmx-cli 0.149.1 is published.

axiom pull ../backend/backend.axiom --framework atmx-web
axiom pull organization/project/1.2.0 --framework flutter --out lib/axiom
axiom pull --contract-config AxiomDeps.toml --framework atmx-react

axiom package

Combine target-specific .axiomapp builds into one multi-target artifact.

axiom package [OPTIONS] <ARTIFACTS>...

All inputs must share one application ID, and each target may appear once. Playground exports already contain their selected targets and cannot be repackaged.

axiom package dist/my-app-web.axiomapp dist/my-app-android.axiomapp

axiom release

Upload a compiled backend artifact to the linked or selected Cloud project as an immutable version. Needs network and axiom login.

axiom release [OPTIONS] [FILE_PATH]

A --version that differs from the compiled version must run from the contract directory: the CLI updates axiom.acore to that version and rebuilds first. Versions may contain letters, numbers, ., _, - and +. If the version already holds different bytes, an interactive release suggests the next free version, and a non-interactive or CI release fails and prints the suggestion. Releasing is not immediate production deployment: Cloud validation, policy, channel and environment state decide the outcome. Frontend snapshots and database packages are local build outputs and cannot be released this way.

axiom build writes to .axiom/contracts/, so pass that path or build with --out:

axiom check axiom.acore
axiom build axiom.acore --out backend.axiom
axiom login
axiom project link
axiom release backend.axiom --version 1.2.0

axiom deploy

Deploy Cloud-side configuration for the linked project.

axiom deploy <COMMAND>

axiom deploy mock-server

Evaluate a local Acore file and upload its mock configuration to the linked Cloud project. Needs network, axiom login and a directory linked with axiom project link.

axiom deploy mock-server [FILE]

Serve the saved configuration with axiom mock --cloud. For a local contract simulation, use axiom mock FILE.acore --profile contract instead.

Measure

axiom benchmark

Measure local backend build time and artifact-load time reproducibly, and write a JSON report.

axiom benchmark [OPTIONS] [FILE]

The report gives the median and p95 of build and artifact decode times, the artifact size and the endpoint count. An existing axiom.axiom in the current directory is restored afterwards. Results describe that machine and checkout: compare reports only with the same inputs and environment.

axiom benchmark axiom.acore --iterations 20 --json