blobhub workflow diff

diff compiles your package in memory, fetches the definitions the revision actually holds, and reports the gap between them. It writes no file, uploads nothing, and creates nothing. It is the command to run before a deploy, and the command to run after one stops. Almost every hint the CLI prints points here, because diff needs only read access and refuses to fail on the input you are trying to understand.

Synopsis

blobhub workflow diff -f <manifest> [--definition <alias>]

Flag	Default	Description
`--file`, `-f`	required	Path to the workflow manifest.
`--definition`	every definition in the manifest	Limit to this alias. Repeatable.

There is no --dry-run and no --force: diff has no side effect to withhold and nothing to overwrite.

It always exits `0`

diff is a report, not a gate. Every state it can discover — a definition missing on either side, a topology that has moved, code that no longer matches, a port edited in the visual editor, even a package that does not compile — is printed, and the exit code stays 0. That is deliberate. diff is the escape hatch that MANIFEST_INVALID, MANIFEST_NOT_FOUND, REVISION_NOT_WRITABLE and REVISION_NOT_ACCESSIBLE all send you to, so dying on a broken import would kill the CLI’s own diagnostic on precisely the input a user runs it to understand. What can still fail is what diff cannot reach: an unreadable manifest, a blob or revision it cannot resolve, a credential problem, a transport failure. Those exit 1 like anywhere else. Once diff has a manifest, a revision and a listing, nothing it finds changes its exit code — so do not use it as a CI gate. To fail a build on a real difference, read the --json payload, or use build --strict-imports for import certainty and check for validity.

What it reports

One block per definition, drift first:

drift: 1 definition(s) on the revision are not in the manifest and were left untouched: playground/checkout_lab (removing them requires 'blobhub workflow prune')
workflow/checkout_flow: both
  components added: c7
  connections changed
  code changed
  state: REMOTE_EDIT
workflow/legacy_flow: remote_only

Line	Meaning
`presence` — `both`	The definition exists locally and on the revision.
`presence` — `local_only`	A `source` file exists; the revision has no such `(category, alias)`. A `deploy` would create it.
`presence` — `remote_only`	The revision has it; the local `source` file does not exist. A `deploy` would fail asking you to `pull`.
`presence` — `absent`	Neither side has it: the manifest names it, but there is no file and no definition.
`components added` / `components removed`	Component ids present on one side only. A `local_only` definition reports all of its components as added, since there is nothing to compare against.
`connections changed`	The two `connections` lists are not identical. This is an exact comparison, so a reordering counts as a change.
`code changed`	For at least one bound component, the freshly compiled content hashes differently from what the revision holds.
`compile error: <CODE>: <message>`	Compilation failed. `code changed` stays absent for that definition — once the compile failed, whether the code changed is unknowable.
`state`	The remote-edit state of the remote definition’s bound code ports.

Under --json the payload carries definitions — each with category, alias, presence, components_added, components_removed, connections_changed, code_changed, compile_error and state — plus drift, alongside the envelope’s schema_version.

The `state` line is about the platform’s copy

build and deploy classify the code port in your local definition file. diff classifies the remote one, which is what makes it the only command that sees a visual-editor edit before you have pulled it.

`state`	What it means	What a `deploy` would do
`MANAGED_CLEAN`	The revision’s code is what the CLI last built.	Overwrite it.
`REMOTE_EDIT`	The revision’s code was edited after the last build.	Overwrite it — the gate reads your local file, not this one.
`UNMANAGED`	The revision’s code was never built by this CLI, or the port is empty.	Overwrite it.

So REMOTE_EDIT here is a warning to act on, not a refusal you will hit later. Pull it, or eject it, before you deploy over it. When a definition binds several code components, the worst state wins, because that is the one that decides what happens next. state is absent when the definition is not on the revision, and when the manifest binds no code components to it.

Compilation is offline here

Like build, diff reads the import allowlist from the local cache rather than fetching it, so it does not need an admin key and works with a stale or missing cache. Unresolved imports raise IMPORT_UNVERIFIED as an advisory; --strict-imports does not exist on this command, since a report has nothing to be strict about.

Errors

Code	When
`MANIFEST_NOT_FOUND`, `MANIFEST_INVALID`, `MANIFEST_TYPE_MISMATCH`, `MANIFEST_VERSION_UNSUPPORTED`	The manifest is absent or unusable. A `source` file that does not exist is not one of these here — `diff` reports it as `remote_only` or `absent`.
`DEFINITION_ALIAS_INVALID`, `DEFINITION_CATEGORY_UNKNOWN`, `DEFINITION_NOT_ACCESSIBLE`	An alias fails the pattern; a category cannot be inferred or contradicts the document; a `--definition` alias is not in the manifest.
`BLOB_NOT_ACCESSIBLE`, `BLOB_NOT_WORKFLOW`	The blob is absent or unreachable with this key, or is not a workflow blob.
`REVISION_NOT_ACCESSIBLE`, `REVISION_NOT_WRITABLE`	The revision is unreachable, or its status is not `ready` — or its phase is none of `draft`, `commit`, `managed`. Reading is the laxer gate, which is why `diff` answers where `deploy` refuses.
`FORMAT_UNSUPPORTED`, `FORMAT_PARSE_ERROR`	A `source` has an unsupported extension, or does not parse.
`CREDENTIALS_NOT_FOUND`, `PROFILE_NOT_FOUND`, `INSECURE_CREDENTIALS_PERMISSIONS`	No usable credential, or a credentials file the CLI refuses to read.
`API_RATE_LIMITED`, `API_TRANSIENT_ERROR`, `API_NETWORK_ERROR`	A call failed after its retries.
`DEFINITION_LIST_TRUNCATED`, `ALLOWLIST_UNREADABLE`, `ALLOWLIST_STALE`, `ALLOWLIST_ENTRY_UNUSABLE`, `ALLOWLIST_SHADOWS_SANDBOX`, `IMPORT_UNVERIFIED`, `LOCAL_SHADOWS_SANDBOX_MODULE`	Advisories, on stderr. The exit code stays `0`.

Every compiler code — IMPORT_UNAVAILABLE, SYMBOL_COLLISION, IMPORT_CYCLE and the rest — appears as a definition’s compile_error rather than as a failure. It is the same code you would get from build, reported instead of raised. Every code above, with its remediation, is in Error codes.

Overview

Workflow

Scheduler

blobhub workflow diff

Synopsis

It always exits `0`

What it reports

The `state` line is about the platform’s copy

Compilation is offline here

Errors

See also

​Synopsis

​It always exits 0

​What it reports

​The state line is about the platform’s copy

​Compilation is offline here

​Errors

​See also

Synopsis

It always exits `0`

What it reports

The `state` line is about the platform’s copy

Compilation is offline here

Errors

See also