opschain admin nodes import

Included from Basic tier

opschain admin nodes import <file.zip> [--into <new-path>]

Recreates an exported subtree's definitions only on the target server, by replaying them through the same ordinary authorised create endpoints a GUI edit uses — nothing is written behind the API's back, and every create is authorisation-checked as you. History never merges into a live instance: the run history and events in the archive stay in the archive, which remains the record of what ran.

What is recreated, in dependency order: the root node, the project's git remotes and templates with their versions, the child nodes (assets re-pin their template versions; archived nodes are re-archived), workflows, triggers, and finally the properties/settings document values. Trigger scope paths that pointed inside the exported subtree are remapped onto the target; scopes outside it travel verbatim.

Entities travel like every other node. An entity's own archive imports onto an entity path (--into demo/entities/rack_2), and the entities inside an exported project, environment or asset subtree are recreated under their recreated parents, with their properties and settings values. Conversion state is not part of the archive: a node left archived by a promotion or demotion imports as an ordinary archived node, without conversion_state or its converted_to link; its opschain_lineage entry travels with its properties.

Two things need attention afterwards:

• Git remote credentials were never exported. Each remote is created without them and the command prints which fields were excluded — re-enter them with opschain git-remotes update.
• The target path must not exist yet. By default the archive's original path is recreated; --into imports under a different path of the same kind (project archive → project path, and so on).

Flags

Flag	Meaning
--into <new-path>	Import under this node path instead of the archive's original path. Must name a path of the same kind as the archive's root, and one that does not exist yet.

Exit codes

Code	Meaning
0	Imported.
1	The archive is unreadable or incomplete, the target exists, or a create was refused mid-import (earlier creates are not rolled back).
2	Usage error — kind mismatch, malformed path, no server target.

Named errors

• the archive holds a project — --into must name a project path, got /projects/… (exit 2)
• /projects/… already exists — import with --into <new-path> to recreate the definitions elsewhere
• /projects/… already exists — --into must name a path that does not exist yet
• the archive holds no nodes
• the archive has no manifest.json / unsupported export format "…" — the file is not a node export.
• creating <kind> /projects/…: <server error> — a mid-import refusal, naming the definition that failed (same shape for templates, workflows, triggers, git remotes and documents).

Examples

opschain admin nodes import demo-export.zip
imported the definitions of /projects/demo into /projects/demo
  git_remotes              2
  nodes                    7
  templates                3
  template_versions        9
  …
history was not imported — the archive remains the record; re-enter any git remote credentials

opschain admin nodes import demo-export.zip --into demo-staging

-o json / -o yaml print the per-type summary counts.

See also

• opschain docs cli/admin-nodes-export — producing the archive (and what it can never contain).
• opschain docs cli/admin-nodes-restore — a soft-deleted node comes back with restore, not import.
• opschain learn 8.1 — backup and interchange, guided.