Export and import a backend

Carry a pipeline graph between workspaces as a single JSON document.

TL;DR

Export writes a backend's graph out as one JSON document.
Import turns that document back into a backend, either as a new project or as a branch of one that exists.
Secrets never travel in the document; they are listed for you to bind after the import.
Both directions are available on the Business and Enterprise plans.

Mental model

A document is a photograph of one working tree. It carries what a commit would freeze — every vertex with its pinned component version, its configuration, its bound files, port bindings, volume mounts and service overrides, plus the connections between them — and it carries the tree as it stands right now, including edits that were never committed. Canvas layout is left out; the import lays the graph out again from its own connectivity.

  source workspace                 destination workspace
  ┌────────────────┐               ┌────────────────┐
  │ working tree   │               │ new repository │
  │  vertices      │  export       │  root commit   │
  │  connections   │ ──────────▶   │  working tree  │
  │  secrets ✗     │  document     │  secrets unset │
  └────────────────┘               └────────────────┘

The document addresses component versions and files by id, so it travels between workspaces of one platform rather than between installations. Secrets are deliberately dropped: a secret parameter's value names a row only its own workspace can read, so the export removes it and records what it removed.

Walkthrough

ppl backend export <backend_id> --output pipeline.jsonppl backend import --file pipeline.json --name "invoice pipeline"ppl backend change-parameter <backend_id> --vertex 3 --name api_key --value <secret_id>ppl backend deploy --backend <backend_id>

Variations

Import into an existing repository with --project and --branch when the graph is another line of work on the same project.
Pipe an export straight into an import with --file - when moving a graph in one step.

Next steps

/flows/test-with-live-backend
/concepts/backend-operations

For exact flag tables, JSON contracts, and error matrices, see the page in the CLI:

ppl docs get flows/backend-portability