--- title: "axiom instance create" description: "Create an Instance node, or append one to an in-development package" category: reference surfaces: [cli] related: [reference/cli/axiom-instance] last_reviewed: 2026-06-06 --- # 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): ```text 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. ```text 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): ```text 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: , 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"). ```text 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. ```text 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. ```text 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. ```text 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 //" 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 ```sh axiom instance create [flags] ``` ## Flags | Flag | Shorthand | Type | Default | Description | |---|---|---|---|---| | `--description` | | string | | Description for THIS instance node; an Instance has no axiom.yaml, so unset ships blank | | `--from` | | string | | Apply a manifest of endpoints to one Instance package (ADR-168 batch; resumable) | | `--generic-node` | | string | | Name of the Generic node within the package (required) | | `--generic-package` | | string | | Generic node's package, scoped as handle/name (required) | | `--generic-version` | | string | | Generic package version to pin (default: resolve and pin "latest") | | `--help` | `-h` | bool | | help for create | | `--input-field` | | key=value | | Input facade field as name=kind (repeatable); kind may be a map | | `--input-field-description` | | key=value | | Docs for one input facade field, as name=text (repeatable) | | `--input-fields-file` | | string | | JSON {message_name,fields} draft for the input facade (excludes --input-message/--input-field) | | `--input-map` | | key=value | | Input-port CEL mapping, dst-field=expression (repeatable); reshapes the facade into generic input | | `--input-message` | | string | | Name for the synthesized input facade message | | `--input-message-description` | | string | | What the input facade message represents | | `--json` | | bool | | Emit a single JSON result object | | `--output-field` | | key=value | | Output facade field as name=kind (repeatable); kind may be a map | | `--output-field-description` | | key=value | | Docs for one output facade field, as name=text (repeatable) | | `--output-fields-file` | | string | | JSON {message_name,fields} draft for the output facade (excludes --output-message/--output-field) | | `--output-map` | | key=value | | Output-port CEL mapping, dst-field=expression (repeatable); reshapes generic output into the facade | | `--output-message` | | string | | Name for the synthesized output facade message | | `--output-message-description` | | string | | What the output facade message represents | | `--package-description` | | string | | Description for the shell PACKAGE; on append, updates it when non-empty | | `--required-secret` | | stringArray | `[]` | A tenant-secret NAME needed at runtime (repeatable); names only, values are set in the console | | `--version` | | string | | Shell package version (semver); default 0.1.0, an append inherits the package's | ## See also - [axiom instance](./axiom-instance.md) — Create Instances from a Generic node (type-bind, no build, no deploy)