opschain workflows import

Included from Basic tier

opschain workflows import <project> -f <file.yaml> [--update] [--code <code>] [--name <name>] [--draft]

Imports a workflow through the ordinary authorised create/update path. This is also the CLI's workflow authoring verb: there is no separate create/update command. Two file formats are accepted, detected from the file itself:

• A flat definition file — the format the local lane runs and repositories commit (.opschain/workflows/*.yaml): recognised by its steps: array and stored on the server verbatim as the definition. Its identity comes from the file's own headers when present — the code from workflow:, the display name from name: (summary: and description: carry over too) — otherwise the code defaults to the filename stem and the name to the code with dashes as spaces. A flat file imports published (draft: false) unless --draft says otherwise.
• The export envelope — the format workflows export writes: recognised by its definition: key and parsed strictly as before — unknown keys fail naming the accepted set (workflow, name, summary, description, draft, definition). An envelope that omits draft leaves the draft state to the server's defaults; name defaults to the code.

--code, --name and --draft override either format's values; a file that parses as neither format is refused naming both and what was missing.

• When the project holds no workflow of the resolved code, the workflow is created (v2 WorkflowService.CreateWorkflow), and the confirmation names the minted version: created workflow <project>/<code> (version <n>).
• When one exists, the import fails unless --update is passed; with it the existing workflow gains the next version, minted from the imported definition exactly as a GUI edit would (PATCH .../workflows/{code} with create_new_version), confirmed as updated workflow <project>/<code> — minted version <n> from <file>.

Whichever format arrives, the definition itself is validated by the server's own workflow authoring machinery, never client-side, so a published (draft: false) import must be runnable to save.

Needs a server target (--server <url>, OPSCHAIN_SERVER, or the active context). -o json|yaml prints the created/updated workflow document instead of the confirmation line.

Flags

Flag	Meaning
-f, --file <file>	The workflow YAML (required): the envelope workflows export writes, or a flat definition file.
--update	Mint the next version of an existing workflow of the same code instead of failing. Harmless when the workflow does not exist yet — the import creates it.
--code <code>	Store under this workflow code instead of the file's (or the filename stem).
--name <name>	Store under this display name instead of the file's (or the derived default).
--draft	Import as a draft (or --draft=false to publish) regardless of the file.

Exit codes

Code	Meaning
0	Workflow created or next version minted.
1	The command failed (already exists without --update, server-side validation refused the definition).
2	Usage error — a file in neither format, malformed envelope, missing -f, no server target.

Named errors

• workflow <project>/<code> already exists — pass --update to mint its next version from <file> — exit 1.
• <file>: not a workflow envelope (missing the definition:key) and not a bare workflow definition (missing thesteps:array) — pass the fileworkflows export writes, or a flat definition file like the ones under .opschain/workflows/ — exit 2.
• <file>: the document must name the workflow (workflow:

  ) — exit
  2 (an envelope without its code).

<file>: unknown workflow document key(s) <keys> (accepted: workflow, name, summary, description, draft, definition) — exit 2.

Examples
# The common case: the flat file the repository already commits.
opschain workflows import demo -f .opschain/workflows/nightly.yaml
created workflow demo/nightly (version 1)

opschain workflows import demo -f .opschain/workflows/nightly.yaml --update
updated workflow demo/nightly — minted version 2 from .opschain/workflows/nightly.yaml

# An exported envelope round-trips unchanged.
opschain workflows import demo -f backups/nightly.yaml --update
See also

opschain docs cli/workflows-export.
opschain docs cli/runs-create — running the imported workflow.
opschain learn 4.1 and opschain learn 8.1.