pull fetches every definition the manifest lists and writes it to that entry’s source file, exactly as the
platform returned it. It is the command that starts a project from a revision someone else built in the browser,
and the command that brings a visual-editor change onto disk where you can read it.
It is a read: it never creates a definition, never modifies the manifest, and needs only a revision it can read.
Synopsis
What it does
- Loads and validates the manifest, then resolves its blob and revision. Reading allows phase
draft,commitormanaged— a committed revision is pullable even though it is not deployable. - Lists the revision’s
workflowandplaygrounddefinitions and matches them against the manifest by the(category, alias)pair. - For each manifest entry, downloads the definition document and writes it to
source, creating any missing parent directories. An entry with no matching definition on the revision is reported, not created. - Prints drift first, then one line per definition:
--json the payload carries pulled, missing, planned, dry_run and drift, alongside the
envelope’s schema_version. planned is populated only under --dry-run, and pulled only without it.
Verbatim, and code-unaware
The document is written as it arrived.pull does not know that a code port holds Python, does not compile
anything, and does not consult the manifest’s components[] bindings at all — a definition entry with no
bindings pulls exactly like one with three.
The file is written in its own format, decided by the source extension: .json gets two-space indent and
a trailing newline, .yaml/.yml gets block style with key order preserved. A playground’s layout round-trips
byte-for-byte, which matters more than it looks: the platform canonicalizes layout at creation and rejects an
upload whose layout differs, so a pull that reshaped it would break the next push.
pull overwrites the local file unconditionally. There is no --force, because there is nothing to guard:
the definition file is an output. If you have local edits you care about, run
diff or --dry-run first.
It never rewrites the manifest
Even whenrevision: latest resolved to a concrete UUID, the manifest is left as written. Rewriting a file you
hand-wrote is a side effect nobody asked for — and if you deliberately pinned a UUID that happens to equal
today’s latest revision, rewriting it to latest would silently change what the manifest means tomorrow.
The first pull of a playground
Category is normally inferred from the local document’s owntype. On a first pull there is no local document
to read, so an entry that declares no category: defaults to workflow — and a playground definition pulled
that way simply reports as missing on the revision. Declare category: playground in the manifest entry for
anything you are pulling for the first time.
--dry-run
Resolves the blob, the revision and the definition set, then reports what it would write without downloading or
touching a file:
Errors
A local file that does not parse still fails the command:
pull reads each source before writing it, to decide
the entry’s category. Delete an unparseable file rather than pulling over it.
Every code above, with its remediation, is in Error codes.
See also
blobhub workflow push— the other half of the pair; a document that goes out throughpushand comes back throughpullcomes back byte-symmetric.blobhub workflow diff— what a pull would overwrite, before it does.- Workflow overview — the project shape and the other nine commands.
- Download Definition — the operation behind each write.