axiom instance create#

Create an Instance node, or append one to an in-development package

Create an Instance: map a Generic node's generalized port(s) onto a real, specific type via a field mapping. There is no build and no Knative deploy — the Instance shares the Generic node's already-deployed image.

The ref takes two forms (ADR-168 instance packages):

handle/package          one node whose name is the package's bare name
handle/package/node     append node "node" to package handle/package

Appending builds up ONE package (e.g. "handle/stripe") with many typed endpoint nodes ("CreateCharge", "ListCustomers", …) that all bind the SAME Generic node, sharing its one image. You may keep appending while the package is unpublished; publishing it freezes the node set (add more in a new version). Every node in a package must bind the same Generic.

axiom instance create handle/stripe/CreateCharge  --generic-package handle/http-tools --generic-node Request ...
axiom instance create handle/stripe/ListCustomers --generic-package handle/http-tools --generic-node Request ...

Or declare a whole package of endpoints at once and apply it (resumable — re-run skips endpoints that already exist):

axiom instance create --from ./stripe-endpoints.yaml

A manifest node's per-port "fields:" value is EITHER a bare scalar-kind string ("count: int64") OR the same rich object form --output-fields-file accepts — "{kind: string, repeated: true}", "{kind: <scalar>, optional: true}", or "{kind: message, message: {message_name: ..., fields: {...}}}" for a nested message (recursively). So a repeated/nested facade field goes inline in the manifest; you do NOT need a separate flag-based --output-fields-file append.

The manifest is parsed STRICTLY: any key the schema does not define is a hard error naming that key, never a silent drop. In particular generic_package, generic_node, and generic_version are TOP-LEVEL keys only — every node in one manifest binds the same Generic, because an Instance package is one image built from one Generic. To bind a different Generic, write a second manifest and run --from again; create appends.

At least one of --output-message or --input-message is required, matching whichever port(s) the Generic node declared generic; each bound message needs at least one --output-field/--input-field as name=kind (repeatable, or comma-separated in one flag: "id=int64,total=double").

axiom instance create acme/orders-query \
  --generic-package acme/postgres-query --generic-node "Postgres Query" \
  --output-message OrderSummary --output-field id=int64 --output-field total=double

axiom instance create acme/orders-query --json    # machine-readable output

For anything beyond a flat scalar field set — repeated/optional modifiers, or a field whose type is itself a nested (not-yet-real) message, recursively — use --output-fields-file/--input-fields-file instead: a path to a JSON file shaped {"message_name": "...", "fields": {...}}, where a field value is either a bare scalar-kind string (as above) or an object like {"kind": "string", "repeated": true} or {"kind": "message", "message": {...}}. --output-fields-file is mutually exclusive with --output-message/--output-field on the SAME port (pick one shape of input); --input-fields-file is likewise exclusive with --input-message/--input-field. The two ports are independent.

axiom instance create acme/orders-query \
  --generic-package acme/postgres-query --generic-node "Postgres Query" \
  --output-fields-file ./order-summary.fields.json

Give a port an authored CEL mapping — exactly the CEL an ordinary edge uses — with --output-map/--input-map as dst-field=expression pairs (repeatable). The output map reshapes the node's generic output INTO the facade; the input map reshapes the facade INTO the node's generic input. A mapping applies to the port it names, which must be bound. A fields-file may also carry a top-level "mapping" object; an explicit --output-map/--input-map flag overrides it.

axiom instance create acme/orders-query \
  --generic-package acme/postgres-query --generic-node "Postgres Query" \
  --output-message OrderSummary --output-field id=int64 --output-field total=double \
  --output-map id=row_id --output-map total="amount * 1.1"

Declare the tenant-secret NAMES this instance needs at runtime with --required-secret (repeatable) — names only, never values. Delivery is per-node and declaration-scoped (ADR-170): any invoking tenant that has configured a value under that name gets it delivered to this node, regardless of who authored the package. A secret's VALUE is set only by a human in the console's Secrets page — there is no CLI command that writes a secret value.

axiom instance create nadia/openai/ChatCompletion \
  --generic-package nadia/http-tools --generic-node Request --generic-version 0.2.0 \
  --required-secret OPENAI_API_KEY \
  --input-map "auth_type='bearer'" --input-map "auth_secret_name='OPENAI_API_KEY'" ...

Use "axiom instance inspect <handle>/<package>/<node>" to see what an Instance actually does (its pinned generic's source, the compiled request/ response adapter mappings, and its declared required secrets) before you configure a secret for it.

Requires a prior "axiom login".

Usage#

axiom instance create <handle/package[/node]> [flags]

Flags#

See also#

• axiom instance — Create Instances from a Generic node (type-bind, no build, no deploy)