---
title: "axiom instance create"
description: "Create a new Instance from a Generic node"
category: reference
surfaces: [cli]
related: [reference/cli/axiom-instance]
last_reviewed: 2026-06-06
---

<!-- GENERATED by docs/scripts/gen-cli-reference — DO NOT EDIT.
     Source of truth: the cobra command definitions in cmd/axiom/cmd/.
     Regenerate from the repo root with: go run ./docs/scripts/gen-cli-reference -->

# axiom instance create

Create a new Instance from a Generic node

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.

<name> is the Instance's scoped name ("your-handle/instance-name") — it
becomes the shell package name and, unqualified, the instance node name.

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"
```

Requires a prior "axiom login".

## Usage

```sh
axiom instance create <name> [flags]
```

## Flags

| Flag | Shorthand | Type | Default | Description |
|---|---|---|---|---|
| `--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` |  | stringToString | `[]` | Input facade field as name=kind (repeatable) |
| `--input-fields-file` |  | string |  | Path to a JSON {message_name,fields} draft for the input facade (mutually exclusive with --input-message/--input-field) |
| `--input-map` |  | stringToString | `[]` | Input-port CEL mapping as dst-field=CEL-expression (repeatable); reshapes the facade into the generic input |
| `--input-message` |  | string |  | Name for the synthesized input facade message |
| `--json` |  | bool |  | Emit a single JSON result object |
| `--output-field` |  | stringToString | `[]` | Output facade field as name=kind (repeatable) |
| `--output-fields-file` |  | string |  | Path to a JSON {message_name,fields} draft for the output facade (mutually exclusive with --output-message/--output-field) |
| `--output-map` |  | stringToString | `[]` | Output-port CEL mapping as dst-field=CEL-expression (repeatable); reshapes the generic output into the facade |
| `--output-message` |  | string |  | Name for the synthesized output facade message |

## See also

- [axiom instance](./axiom-instance.md) — Create Instances from a Generic node (type-bind, no build, no deploy)