Contract, package and security commands

These commands manage what a frontend depends on (contract locks, typed frontend packages, and third-party packages for authored extensions) and analyze a backend contract's optional domain and security layers. This page covers Axiom CLI 0.149.1. None of them needs a Cloud login; only dependencies resolve and dependencies cache recover contact package registries over the network.

Axiom Marketplace is Coming soon. The packages commands do not discover or install packages from a catalog; they consume explicit package files and locks.

Diagram source

flowchart LR
  Deps[AxiomDeps.toml] --> CResolve[contract resolve]
  CResolve --> ULock[UI contract lock]
  ULock --> CVerify[contract verify]
  ULock --> CCheck[contract check-source]
  ULock --> CDiff[contract diff in review]
  Deps --> PResolve[packages resolve]
  PResolve --> PLock[package lock]
  PLock --> PVerify[packages verify]
  PLock --> PCheck[packages check-source]

AxiomDeps.toml declares the contracts and packages a frontend uses. contract resolve and packages resolve turn it into deterministic locks under .axiom/. In CI, verify re-resolves the manifest and fails if the committed lock differs, check-source validates imports against the lock alone, and the diff commands show semantic changes for review.

axiom contract

Resolves and verifies the signed backend contract artifacts that a frontend imports with use contract, and records them in a deterministic UI contract lock. Normal development through axiom run FRONTEND.acore discovers the manifest and maintains an internal development lock under .axiom/dev automatically. Use these commands to manage a reviewed lock for CI and release workflows.

axiom contract <COMMAND>

No options other than --help.

A frontend manifest names each contract alias, its artifact and the operations it uses. This is the task-app example:

type = "frontend"
targets = ["web"]

[contracts.tasks]
artifact = "../backend/.axiom/contracts/backend.axiom"
baseUrl = "http://127.0.0.1:8080"
audience = "web"
operations = ["create_task", "delete_task", "list_tasks", "update_task"]

An entry that points at an unsigned local artifact produces a warning: it is allowed for development, and you release the contract through Axiom Cloud before production use.

axiom contract resolve

Resolves the contract entries in AxiomDeps.toml into a deterministic lock. When the lock already exists and changes, it prints the semantic diff as JSON before writing. It reads only the local artifacts the manifest names. With the default --lock, the lock path is relative to the manifest's directory.

axiom contract resolve [OPTIONS]

axiom contract resolve

axiom contract verify

Re-resolves the manifest and checks every locked input, byte for byte, without changing files. Use it in CI. On a mismatch it fails and asks you to resolve and review the semantic diff. On success it reports how many aliases are signed and unsigned.

axiom contract verify [OPTIONS]

axiom contract verify

axiom contract diff

Prints the semantic changes between two UI contract locks as JSON. Use it to review a lock update.

axiom contract diff <BEFORE> <AFTER>

axiom contract facade

Prints read-only virtual-facade metadata for one locked alias: the typed interface the UI compiler derives for that contract. No facade file is generated.

axiom contract facade [OPTIONS] <ALIAS>

axiom contract check-source

Validates the use contract declarations in one source file against only the committed lock. It never resolves or writes files, and exits non-zero with one diagnostic per problem.

axiom contract check-source [OPTIONS] <SOURCE>

axiom contract check-source main.acore

axiom packages

Builds, resolves, verifies, inspects, diffs and source-checks typed frontend .axiom packages, such as theme and component libraries. Resolution reads only local files inside the manifest's directory, and rejects an artifact that resolves outside it. See Packages.

axiom packages <COMMAND>

No options other than --help.

axiom packages build

Validates a typed package envelope, writes its canonical encoding to --out, and prints the output path and SHA-256 digest.

axiom packages build --out <OUT> <SOURCE>

axiom packages resolve

Resolves the package entries in AxiomDeps.toml into a canonical lock that you commit. It validates the complete lock before replacing any output.

axiom packages resolve [OPTIONS]

axiom packages resolve

axiom packages verify

Re-resolves the manifest and verifies every locked package's bytes and proofs without changing files. Use it in CI.

axiom packages verify [OPTIONS]

axiom packages verify

axiom packages inspect

Prints one verified locked package envelope as JSON.

axiom packages inspect [OPTIONS] <ALIAS>

axiom packages diff

Prints a semantic diff of two encoded packages as JSON, then fails unless every change that needs review is approved. Approval values are breaking-change, target-reduction, new-required-theme-role and permission-increase.

axiom packages diff [OPTIONS] <BEFORE> <AFTER>

axiom packages diff theme-1.0.0.axiom theme-2.0.0.axiom --approve breaking-change

axiom packages check-source

Validates package imports against the package lock and compiles the unchanged source for one target. It writes no files and exits non-zero on a diagnostic.

axiom packages check-source [OPTIONS] <SOURCE>

axiom packages run

Runs package-backed source through the normal target host session, like axiom ui run with a package lock. Host and Node.js requirements are the same as for ui run.

axiom packages run [OPTIONS] <SOURCE>

axiom dependencies

Resolves and audits third-party packages that authored executable extensions use. The manifest is AxiomDeps.toml in its strict v2 schema, which declares registries and build environments. Resolution writes the canonical lock .axiom/AxiomDeps.lock, stores artifacts in an immutable content-addressed cache, and materializes a workspace view. Package scripts and advisories are recorded, never executed. Executable extensions are Experimental; see Extension dependencies.

axiom dependencies <COMMAND>

No options other than --help.

When --cache is omitted, the cache is axiom/dependencies/v1 inside the user cache directory.

axiom dependencies check

Validates the complete AxiomDeps.toml v2 document without fetching anything. It prints the canonical manifest digest and the number of contracts, packages, extensions and build environments, and exits non-zero on the first problem.

axiom dependencies check [OPTIONS]

axiom dependencies check

axiom dependencies format

Canonically formats a v2 manifest. By default it prints the formatted manifest to standard output.

axiom dependencies format [OPTIONS]

axiom dependencies migrate

Converts a supported v1 manifest to the strict v2 schema in memory. By default it prints the result to standard output.

axiom dependencies migrate [OPTIONS]

axiom dependencies schema

Prints the checked-in AxiomDeps.toml v2 JSON Schema, for editors and validation tools.

axiom dependencies schema

No options other than --help.

axiom dependencies completions

Returns deterministic editor completion candidates for a position in the manifest, given as a TOML path.

axiom dependencies completions [OPTIONS]

axiom dependencies hover

Explains one AxiomDeps.toml v2 field. It fails when the path has no documentation.

axiom dependencies hover [OPTIONS] <PATH>

axiom dependencies resolve

Resolves exact package graphs from the registries the manifest declares, verifies and stores every artifact in the cache, writes the canonical lock and materializes the workspace view. It needs network access to those registries unless you pass --locked or --offline. Direct exact-version conflicts are rejected before any network request.

axiom dependencies resolve [OPTIONS]

With --locked or --offline, the lock must match the current manifest and the cache must hold every locked artifact.

axiom dependencies resolve
axiom dependencies resolve --locked

axiom dependencies verify

Validates the canonical lock and every cached byte it references, offline. It fails on a corrupt or malformed cache object. Use it in CI.

axiom dependencies verify [OPTIONS]

axiom dependencies verify

axiom dependencies inspect

Explains the environments, provenance, licenses, advisories and package scripts recorded in the lock.

axiom dependencies inspect [OPTIONS]

axiom dependencies cache

Verifies, prunes or recovers the immutable authored-dependency cache.

axiom dependencies cache <COMMAND>

No options other than --help. The subcommands are verify, prune and recover.

axiom dependencies cache verify

Checks every object in the cache against its digest and exits non-zero when any object is corrupt or malformed.

axiom dependencies cache verify [OPTIONS]

axiom dependencies cache prune

Removes cache objects that none of the given locks reference. It requires at least one --lock; there is no implicit global deletion.

axiom dependencies cache prune [OPTIONS] --lock <LOCKS>

axiom dependencies cache recover

Downloads the cache objects a lock needs from their recorded registries and verifies them. It needs network access.

axiom dependencies cache recover [OPTIONS]

axiom domain

Validates or bootstraps the optional Domain Model v1 layer of a backend contract. See Domain and security models.

axiom domain <COMMAND>

No options other than --help.

axiom domain validate

Validates domain references and prints the canonical domain manifest hash with the number of entities, relationships and projections. A contract without a domain block is reported as such and the command succeeds.

axiom domain validate [OPTIONS] [FILE]

axiom domain validate main.acore --json

For the hello-api example, which declares no domain block, the output is:

{
  "format": "none",
  "message": "No optional domain block is declared."
}

axiom domain bootstrap

Writes a reviewable Domain Model v1 block from OpenAPI JSON or exported SQL DDL. It writes suggestions only: it never modifies the input or your contract and never connects to a live database. It refuses to overwrite an existing output file, and the input limit is 8 MiB. Review model names, ownership, audiences and invariants before you copy the block into axiom.acore. OpenAPI and SQL input is Experimental and bounded; it is not full behavior or runtime parity. See Existing database.

axiom domain bootstrap [OPTIONS] --source <SOURCE> <INPUT>

axiom domain bootstrap openapi.json --source openapi

axiom security

Inspects the opt-in Security Model v1 policy, its source evidence and its coverage. See Domain and security models and Security rules.

axiom security <COMMAND>

No options other than --help. The only subcommand is check.

axiom security check

Runs the same deterministic security analysis as axiom build without writing an artifact. It renders the manifest a build embeds: mode, findings, coverage, policy graph, source evidence and canonical hash. Run it locally, in CI and before a release. It does not read secret values.

axiom security check [OPTIONS] [FILE]

axiom security check axiom.acore
axiom security check axiom.acore --json > security-report.json
axiom build axiom.acore --out backend.axiom

For the hello-api example with security(mode: "audit") added, the report lists one warning and the command exits with status 0:

Security Mode audit · 0 error(s), 1 warning(s) · 0 of 1 endpoints covered (0 direct, 0 default-policy)
AXSEC-001 WARNING [hello] `hello` is externally reachable but has no explicit public declaration or authorization policy.
  → Declare `security.endpoints[endpoint]` as public or bind it to a user-defined policy.

Exit status

Recommended rollout

1. Run a Go or Python extractor and review its advisory facts.
2. Add security(mode: "audit"), explicit public routes and policies.
3. Classify sensitive fields and add response projections.
4. Declare network, upload, path, process, cache, CORS and logging controls only for boundaries the service actually owns.
5. Review each security change in a native contract pull request.
6. Move to strict after a trusted server adapter enforces the declarations.

Put policy-safe identifiers such as origins and issuers in Acore, and keep credentials in deployment secrets. See Production readiness for the release review.