VS Code extension

The Celigo extension for VS Code and Cursor opens a flow, tool, or API from the tree celigo pull writes as the Flow Builder canvas — the Flow Canvas. It draws a flow.json, tool.json, or api.json with its step components, mappings, and scripts. It marks the steps with the tree's lint findings and status badges and, on request, the account's open errors — which you can open, retry, and resolve from the canvas. Edits go back to the account through celigo push. Other VS Code-based editors that install from Open VSX work the same way. This page describes extension 1.1.0.

The graph comes from the CLI's own engine, celigo flows graph, a port of Flow Builder's graph algorithm. The canvas shows what the product would show for the same document. See The local tree for the tree the canvas opens and flows graph for the engine.

Requirements

• VS Code 1.104 or later, or Cursor. Other editors built on VS Code install the extension from Open VSX.

• The Celigo CLI 2026.9.1 or later on your PATH, or at the path in celigo.cliPath. Lint findings, the live overlay, and push need it; rendering and editing work without it. When no celigo answers, the extension offers once per session to run the CLI through npx, pinned to the version it needs.

• Node.js 22 or later for the CLI. See Install.

Install

Install from a terminal:

# VS Code
code --install-extension Celigo.celigo

# Cursor
cursor --install-extension Celigo.celigo

Or install from the Extensions view: search for Celigo by the publisher Celigo and click Install. VS Code installs from the Visual Studio Marketplace; Cursor and other editors install from Open VSX. ext install Celigo.celigo in Quick Open does the same.

Or install a downloaded VSIX:

code --install-extension celigo.vsix      # VS Code
cursor --install-extension celigo.vsix    # Cursor

Open the canvas

1. Pull a tree with the CLI.

   celigo pull                        # the whole account
   celigo pull --integration <id>     # one integration

2. Open a flow.json, api.json, or tool.json from the tree.

3. Press Cmd/Ctrl+Shift+V to open the canvas beside the editor.

The preview icon in the editor title opens the canvas beside the editor too. To open it in the current editor group, run Celigo: Open Flow Canvas from the Command Palette. The same command is on the editor's context menu and on the Explorer's context menu for flow.json, tool.json, and api.json.

A JSON document outside a tree whose shape is a flow, tool, or API renders too. Its references stay unresolved, and the features that need the tree — badges, lint findings, the live overlay, push — are off.

Read the canvas

The canvas draws the document the way Flow Builder does: sources on the left, destinations and lookups to the right, branchings with their branch names, merge points, and terminals. Each step's step components — filters, transformation, mapping, hooks, results/response mapping, error handling — appear as chips in the positions Flow Builder shows them. Tools (tool.json) and API builders (api.json) render with their own shapes.

The canvas reads the tree, not only the open file. Every step resolves through the pulled tree's manifest: its name, its category, the application behind its connection, and its step components. Symlink and pointer trees work. In a celigo pull --neutral tree, the bindings resolve connection names.

The canvas follows the editor:

• Unsaved edits re-render as you type.

• Moving the caret in the JSON highlights the step it is in.

• Double-clicking a step, or Go to step in flow.json in its ⋯ menu, jumps to the step's definition.

• Open export file, Open import file, Open AI agent file, and the other items named for the step's type open the document the step references.

Badges show the tree's state. celigo status badges (modified, missing, untracked) sit on the flow and on each step's document. celigo lint findings sit on the steps they concern.

Flows drill down. Flows started by this one (_runNextFlowIds) and an instance's abstract flow open in their own canvas.

Find node in the toolbar (Cmd/Ctrl+F while the canvas is focused) matches step names, applications, resource types, resource and connection names, and branch names, word by word. Press Enter or Shift+Enter to walk the matches; each match is selected and centered at the current zoom. Press Esc to clear. Steps that do not match are dimmed so the matches stand out.

Interaction	What happens
Click a step	The details panel shows its facts, its Live section (live overlay on), its step components, its Related tree, and its JSON (Step and Resource), each section folding from its header. A collapsed panel stays collapsed — its rail's chevron shows a dot for the selection — and folded sections stay folded.
Double-click a step, or Go to step in flow.json in its ⋯ menu	The editor jumps to the step's definition in the document (api.json or tool.json for those).
Open export file in the ⋯ menu (Open import file, Open lookup file, Open AI agent file — the step's type)	The document the step references opens in its own editor.
Click a step component chip	Its configuration opens in the details panel, with its Related item selected (a folded Related tree or JSON section unfolds).
Click a step's live error count (3 errors)	The step is selected and its open errors are listed in the Live errors list of the details panel's Live section, which unfolds if folded (live overlay on; read through the CLI). See Live errors.
Click the toolbar's 139 open errors or remote changed badge	The details panel opens on the flow's Live section: every step with open errors as a link, and, when celigo diff confirmed the server copy changed since the pull, the Pull latest and Compare buttons, the celigo diff line, and the Pull everything link. See Drift.
Pull latest in the Live section	Takes the server's copy of this document — celigo pull --force <path> through the CLI, only this file forced — and shows the CLI's summary line. A clean document is pulled at once; one with local edits asks first; an unsaved editor buffer asks what to do with the edits first. See Pull latest.
Compare / Pull everything in the Live section	Compare runs the quoted celigo diff line in a terminal — nothing written. Pull everything runs the plain incremental celigo pull of the whole tree in a terminal: files the server changed are refreshed, local edits kept, deletions only reported.
Live (the dot · Live · ↻ button)	Re-reads the live overlay now; its tooltip says when it was last read and how often it refreshes on its own while the canvas is visible.
Open › on a listed error	The error's fields, its retry data (the record), and its request and response open in the section, read-only; Copy JSON and Open in editor give you the whole payload.
Retry / Resolve on a listed error (or in the error view's title line)	Retry sends the record through the step again — celigo flows retry-errors through the CLI, one record, no confirmation; disabled with the reason on an error without retry data. Resolve takes the error off the open list for good — celigo flows resolve-errors — after a modal. Both run under the tree's profile in its permission mode: a read-mode profile gets the CLI's refusal in the list, with the terminal line.
Retry all / Resolve all above the list, or Retry selected / Resolve selected with rows checked	Every open error on the step (the CLI pages them all — not only the 50 listed) or the checked ones, after a modal naming the count, the step, and the profile. A retry is queued as a job: the count drains as it completes.
Click a Related script or Instructions item	The script.js or instructions.md loads in the details panel as its own tab.
Cmd/Ctrl+F	Find node matches step, application, resource, connection, and branch names. Enter and Shift+Enter walk the matches.
Cmd/Ctrl+\, the chevron in the details panel's header, or View › Show details panel	Collapses the details panel to a rail so the canvas takes the room, or opens it again at its previous width.
A section's header (Facts, Live, Step components, Related, the JSON section's tabs row)	Folds or unfolds that section (Enter or Space on the focused header does the same). The sections above the editor scroll as one, so a folded section gives its room to the others.
The grip on the divider above the JSON section	Drag to split the panel between the sections and the editor (ArrowUp / ArrowDown 16 px, Home / End to the floors); double-click for the default half.
Edit	Turns on the Flow Builder affordances: + on edges, the add and remove items in the step and branching menus (a dashed placeholder step's ⋯ has Remove step), branch and merge operations (a branch end's menu removes an empty branch), the Enabled / Disabled switch, and an editable JSON panel. In view mode those menus say Turn on Edit to….
Push	Runs celigo push --dry-run, then celigo push, in a terminal for this flow and every referenced file with local changes. Push sends what is on disk: when the document or a related file it would send has unsaved edits, a modal names them and offers Save all and continue, or Cancel.

The details panel

Click a step to open the details panel. Since extension 1.1.0 it is a stack of sections, each folding from the chevron in its header (Enter or Space on the focused header does the same):

• Facts — the flow's kind, id, state, schedule, and step count; or the step's type, app, resource, document, pointer, branch, and routing rows, with the lint findings, Move left / Move right, and the branching editor.

• Live — with the live overlay on: the flow's server state, drift, and celigo diff line and the steps with open errors; for a step, its Open errors count and the Live errors list or error view it opens. See Live overlay.

• Step components — the step's chips.

• Related — everything the step reaches in the tree, with its count badge. See The Related tree.

• JSON — the editor, whose header keeps the Step / Resource / Script / Instructions tabs and Open in editor while its body is folded. Folding it gives the whole height to the sections above.

A fold hides a section in place: the editor keeps its unapplied draft and undo history, an error view its tab, the tree its selection. An action whose effect lands in a folded section unfolds it — a step component chip unfolds Related (and JSON once the item is in the editor), a live error count or a toolbar live badge unfolds Live, a Related item unfolds JSON — while selecting a step leaves your folds alone. The sections above the editor scroll as one, so a folded section hands its room to the others.

Collapse and resize

• Collapse. The chevron in the panel's Details header (Collapse panel), View › Show details panel in the toolbar, or Cmd/Ctrl+\ while the canvas is the active editor folds the panel to a slim rail at the canvas's right edge; the canvas takes the room, and Fit to screen and the zoom floor follow. The rail's chevron (Expand panel) opens it again at the width it had. Selecting a step leaves a collapsed panel alone — the rail's chevron shows a dot while a step is selected — whereas clicking a step's live error count or a step component chip, whose whole effect is in the panel, opens it. Cmd/Ctrl+S with the panel collapsed applies nothing and says so beside the rail.

• Resize. Drag the grip on the panel's left edge (Drag to resize · double-click to reset): 240 px at the narrowest, up to what leaves the canvas 320 px in the window as it is now, so a narrowed window shrinks the panel and a widened one gives the chosen width back. Double-click the grip for the 380 px default. The handle takes the keyboard too — arrows in 16 px steps, Home / End for the narrowest and widest.

• Split. Drag the grip on the divider above the JSON section to split the panel between the sections and the editor. Neither side goes under 120 px; ArrowUp / ArrowDown move it 16 px, Home / End to the floors; double-click puts the default back — the JSON section at half the height. The splitter hides while the JSON section is folded. What is stored is the JSON section's share of the height, not a pixel height, so a dragged split looks the same in a maximized and a half-height editor group.

Width, collapse, the folded sections, and the split are remembered together across reloads.

JSON tabs

Step shows the step's own object in the flow. Resource shows the export or import document it references from the tree. With nothing selected, the editor shows the whole document. In view mode the editor is read-only.

In Edit mode, changes stay local until you click Apply or press Cmd/Ctrl+S; Esc reverts them. The editor lints changes inline and runs them through the same guards as canvas edits: an instance flow is refused, and so are the responseMapping object wrapper and fields: null. An applied edit is written as canonical JSON over exactly the step's range in the document — or over the resource file's full text — and leaves the document dirty for you to save. When the document changes underneath unapplied edits, a banner offers Reload or Keep mine.

The Related tree

Above the JSON, the Related tree lists everything the selected step reaches in the tree, in Flow Builder order:

• The step's entry in the document.

• One item per step component. Hooks expand per stage, each with its script beneath.

• The export or import document, with its connection and every other reference.

• For an AI agent or guardrail step, its Instructions: the instructions.md the tree keeps the system prompt in.

• The flow-level links: _runNextFlowIds and an instance's abstract flow.

JSON items open in the editor as their own tab. They apply pointer-exact to whichever tree file they live in, under the same guards as a step edit. A script loads as a Script tab: its script.js with JavaScript highlighting, opened at the function the hook names. An AI agent's instructions load as an Instructions tab: its instructions.md with Markdown highlighting. Both are editable in Edit mode, and Apply writes the whole file back verbatim. The row's open in editor link opens the file in a full editor beside the canvas. A reference the tree cannot resolve shows its id, muted, with a where it's written link to the referencing field.

Clicking a step component chip on a card does the same as its tree item. Arrow keys move between items.

Edit and push

Edit turns on the Flow Builder affordances:

• + on any edge adds a step or a branching.

• Step menus add, remove, and reorder steps and toggle error handling. The details panel's Move left / Move right reorder a step within its branch; since extension 1.1.0 they are offered only where the neighbour in that direction is a step, so a branch's last step moves left only, its first right only, and a lone step neither.

• A dashed Add destination / lookup placeholder — the unconfigured step that + › Add destination / lookup inserts ({ "setupInProgress": true }, the entry Flow Builder saves while a step is being set up) — and its Add source twin carry the card's ⋯ menu, cut to what a placeholder is: Go to step in flow.json (double-click does the same) and, in Edit mode, Remove step / Remove source (since extension 1.1.0). The flow's only source keeps its slot, as Flow Builder always shows one.

• Branch ends merge into a merge point or another branch. Merge points unmerge. In Edit mode a branch end's menu also has Go to branch in flow.json and, when the branch has no steps, Remove branch "" (since extension 1.1.0); a branching's last branch is refused — remove the router instead.

• Branchings gain branches and names.

• The Enabled / Disabled switch beside the flow's name toggles disabled. Outside Edit mode it is a read-only badge.

In view mode the step and branching menus say Turn on Edit to… where the structural items would be.

Every edit is written to the open document as canonical JSON through the CLI's own mutation rules — the same JSON Flow Builder saves. Undo works, and celigo status sees exactly the change. Canvas and JSON edits are ordinary unsaved edits to the document: Cmd/Ctrl+Z undoes them one at a time, File: Revert File drops them all, and Pull latest replaces the saved file with the server's copy. Nothing reaches the account until you push.

⚠️ Push writes to the account. Push runs celigo push --dry-run, then celigo push, in a terminal, with the profile the CLI resolves there (CELIGO_PROFILE, or the active profile). The push runs only when the dry run succeeds, so a refused plan stops before anything is sent — read the plan the dry run prints. celigo push needs a profile in full mode. It sends what is on disk: when the document or a related file it would send has unsaved edits, a modal names them — flow.json has unsaved edits. Push sends what is on disk. — and offers Save all and continue, which saves the document and each named related buffer and goes on to the terminal, or Cancel, which leaves everything as it is. A save the editor could not make stops the push (Push did not run: … could not be saved). There is no Revert here; File: Revert File is a keystroke away.

Push covers this flow and its changed step documents and scripts: the flow's document first, then every file its steps reference that celigo status reports as modified, or as untracked when push can create it — an import edited in the Resource tab, a hook's script.js, an AI agent's instructions.md, a modified connection — each named on the terminal's line. --prune is never passed; a missing file is left to the plan's notes. The extension holds no token. Anything that needs credentials runs the installed celigo binary, and celigo push is the only writer. See push for the plan, the check against the server copy, and --prune.

Layout and export

The toolbar's View menu holds Fit to screen, which shows the whole graph however large it is, and Horizontal layout / Vertical layout, which flip one canvas without changing the setting. celigo.canvas.direction sets the default. The vertical layout is Flow Builder's layout transposed — the same rules and the same spacing, top to bottom — with the step component chips in columns above and below each card and the sources in a row centered over the trunk.

The toolbar's Export menu saves a PNG or SVG image of the whole canvas, or copies a Mermaid diagram that renders natively in a GitHub pull request description. The diagram follows the canvas's direction: flowchart LR for horizontal, flowchart TD for vertical. Celigo: Copy Flow as Mermaid in the Command Palette copies the same diagram; without an open canvas it follows the setting.

Live overlay

The live overlay is off by default. With celigo.canvas.liveOverlay set to true, the canvas reads the account the tree is bound to, through the CLI in read mode — celigo flows get and celigo flows error-summary: open-error counts per step, whether the flow is enabled on the server and its last run, and whether the server copy changed since the pull. The overlay itself writes nothing; the only account writes the canvas runs are the Live errors list's explicit Retry / Resolve (below).

Badges and the Live button

Since extension 1.1.0 the toolbar sums the overlay up beside the flow's name as quiet badges styled like the tree-state badges: a red 139 open errors (hidden at zero) and an amber remote changed when the server copy changed since the pull, or one muted live unavailable carrying the CLI's own message when the read failed. Each opens the details panel's flow-level Live section — expanding a collapsed panel — which explains the drift in words, quotes the celigo diff <path> --dir <root> line to run, and lists the steps with open errors as links. The panel's Live section also reports Enabled on the server or Disabled on the server.

At the toolbar's right, the Live button carries a status dot — grey until the first read, green when clean, red for open errors, amber for a confirmed change, hollow when unavailable — and a refresh glyph that spins while a read is in flight. Click it to read now. Its tooltip says Updated 40 s ago · refreshes every 60 s while visible, then the flow's state on the server, its last run, the profile, and the drift. Celigo: Refresh Live Overlay in the Command Palette reads too.

Timed refresh

While a canvas is visible and the window focused, the extension re-reads the overlay every celigo.canvas.liveRefreshSeconds (60 by default; values below 15 are raised to 15; 0 for on demand only) — the same two read-mode CLI calls as the Live button, never overlapping: a tick that falls due while a read is in flight is skipped, and a click, a save, or the palette command joins the read in progress rather than starting another. A hidden canvas or an unfocused window pauses the timer; coming back reads at once when the last read is older than the interval, else waits out the remainder. After a failed read the wait doubles, up to ten minutes, until a read succeeds. Restricted Mode and an overlay turned off run no timer. Nothing detects a push — save, click Live, or wait for the tick.

Drift

Remote changed means a confirmed content difference. The server's lastModified against the token the tree pulled is only the first signal: the platform bumps that token for a flow run and for a debug toggle — fields celigo pull strips and celigo diff ignores — so a flow that had merely run since the pull used to wear the badge (extension 1.0.0). Since 1.1.0, when the two tokens differ the extension runs the CLI's own comparison — celigo diff <path> --dir <root> [--profile <p>] --format json, read mode, in the tree — and the drift is one of three:

Drift	Badge	The Drift row
In sync — the tokens agree; no diff runs.	none	in sync
Timestamp moved — the diff finds the content identical.	none	timestamp moved — the server's timestamp moved since the pull (a run or a debug toggle); the content matches your file, with Pull latest offered as a token refresh (the file is not rewritten) and Compare in the plain style.
Remote changed — the diff reports differences.	amber remote changed (the count in its tooltip)	remote changed — 3 differences from your file (on a document that also has local edits, some of the differences may be yours), with Pull latest, Compare, and Pull everything.

When the diff itself fails — a server error, a refusal — nothing is claimed: the row says the content was not compared, an error-toned line gives the CLI's reason (could not compare: …), the celigo diff line is quoted to run yourself, and the next refresh tries again. The comparison runs only while the tokens differ and once per state; its result is kept until the server's token, the pulled token, or the file on disk moves. The pulled token is re-read from the tree's manifest on every read, so a celigo pull you run in a terminal clears the drift on the next tick.

Pull latest

Under the Drift row, Pull latest takes the server's copy of this document: celigo pull --force <path> --dir <root> [--profile <p>] through the CLI, in the extension host's own process (an argv, never a shell line), under a progress notification with ten minutes to finish. --force reaches only this document; the rest of the tree is pulled incrementally around it, never with --prune or --allow-account-mismatch. What happens is decided on the host before anything spawns:

The document	What Pull latest does
Has an unsaved editor buffer	Asks first — flow.json has unsaved edits. Pull replaces the file on disk. — with Save and continue (the edits stay in the file, and the pull then asks before discarding them, below), Revert and continue (the unsaved edits are dropped, as File: Revert File drops them, and the file as saved is pulled), or Cancel. A buffer still dirty afterwards, or a save the editor could not make, is a refusal that names what to do in the editor.
Is clean in celigo status	Pulled outright — nothing local is lost.
Has local edits since the last pull	Asks first — Order Sync has local edits since the last pull. Take the server's copy and discard them? — with Take server copy, Compare first (the diff in a terminal), or Cancel.
Is missing or untracked, outside a tree, or in a tree whose status cannot be read	The button is disabled with the reason in its tooltip (Restricted Mode and a missing CLI disable it as they disable Live).

The CLI's summary line becomes the section's note — Took the server copy of flows/Order Sync/flow.json. Pulled 1, renamed 0, unchanged 245 (of 246). — with the CLI's own notes beneath it, or … already matched the server copy; its pulled token was refreshed when only the token had moved; a failure shows the CLI's last line. The document is rewritten on disk, so the editor reloads its clean buffer, the canvas re-renders from the new text, the tree-state badge clears, and the overlay is re-read against the manifest's new token so remote changed goes.

Beside it, Compare runs the quoted celigo diff line in a terminal — your file against the server copy, nothing written — and, for a confirmed change, the Pull everything link runs the plain incremental celigo pull of the whole tree in a terminal: every file the server changed is refreshed, local edits are kept, deletions are only reported. See pull for --force and status and diff for the comparison.

Live errors

Click a step's error count on its card (3 errors), or the Open errors row of the step's Live section, to list the step's open errors in a Live errors list under it, read through celigo flows errors <flow> <step> — a read-mode verb, against the tree's profile like the rest of the overlay. Each row shows the error's code, classification, whether it can be retried, when it occurred, its message (clamped; click to unfold), and the errorId and trace key a terminal continues with. The list shows the newest 50 and names the exact terminal line for the rest (2 more — run celigo flows errors … --profile … in a terminal), has Refresh and Hide, says No open errors when the step has none, and shows the CLI's own error line (a missing profile, a revoked token) when the listing fails. The flow-level Live section lists every step with open errors, most first, each a link that selects the step and opens its list. Where the CLI cannot run — Restricted Mode, no CLI installed — the count is a plain status whose tooltip says why.

Open › on a row opens an error view — what Error Management shows when an error is clicked — read-only:

Tab	Contents	Read through
Error	The message unclamped and every field the record carries: occurred, code, classification, retryable, source, error ID, trace key, flow job, oIndex, purge time.	The listing.
Record	The retry data — the record as the step saw it when it failed, in the envelope a retry re-feeds — as JSON in the panel's read-only editor, with the envelope's stage, source export, one-to-many path, and trace key as rows.	celigo flows error <flow> <step> <errorId> --retry-data
Request / Response	The stored HTTP pair: method and URL, status and time received, headers, and the body as JSON when it parses, as text otherwise.	celigo flows error <flow> <step> <errorId> --request-detail

Each payload is read on the first tab that needs it, under the same gates as the list. A tab the error has nothing for is disabled and its tooltip says so in the CLI's words — no retry data on a connection-class error, no stored request or response on a non-HTTP step. Copy JSON on every tab and Open in editor on the payload tabs read the whole payload on the host and open it as an untitled JSON document beside the canvas; nothing is written to disk, and the panel itself receives at most 512 KB per payload — past that it shows only the size. In the Request and Response tabs the host replaces every header and query-string value whose name reads as a credential (authorization, cookie, token, secret, password, api key) with ••••••, on top of the platform's own ********, and the tabs say so. Retry data and bodies never reach a log or an error message. Back returns to the list; a Refresh, another step, or Hide drops the view.

Retry and resolve. The list acts on what it lists (since extension 1.1.0):

Control	What it does	Asks first?
Retry on a row (and in the error view's title line)	Sends that one record through the step again. Disabled with the reason on an error without retry data — a connection or governance error has no record to send again; resolve it instead.	No.
Resolve on a row (and in the error view's title line)	Takes the error off the open list for good.	Yes — Resolve 1 error on ?
Retry all / Resolve all above the rows	Every open error on the step — the CLI pages them all server-side, not only the 50 the panel lists.	Yes — Retry 158 open errors on ? Each record is sent through the step again — the destination receives it again … / Resolve 158 open errors on ? Resolved errors leave the open list and cannot be reopened …
Retry selected (n) / Resolve selected (n), with rows checked	The checked errors; a retry counts only the checked errors that can be retried, and its tooltip names the ones it skips. Clear selection sits beside them.	Yes.

Each modal names the count, the step, and the profile the CLI runs under — the account the answer commits to. Each action is celigo flows retry-errors <flow> <step> [<retryDataKeys>] [--yes] or celigo flows resolve-errors <flow> <step> [<errorIds>] [--yes], run by the extension through the CLI in its own process (an argv, never a shell line), --yes only for all, the modal having asked — the CLI's own [y/N] needs a terminal the host has none of. The commands run against the tree's profile in whatever permission mode that profile has: a read-mode profile gets the CLI's refusal in the panel — Read mode: blocked POST v1/flows/…. Switch with 'celigo config set mode operate' (or 'full'), or use a different profile. — with the terminal line to run instead, never a silent nothing. The CLI's outcome lines become the list's note: Retry queued for 3 record(s). (job …) — a retry is a job the platform runs, so the open count drains as it completes rather than dropping at once — Resolved 158 error(s)., and the … matched no open error / … were not listed on this step lines for keys that matched nothing; a run that changed nothing is the CLI's own sentence in the error tone, as is any other failure, each with the terminal line. While the modal or the CLI has the request the buttons wait and the list says so (Waiting for your answer in the dialog…, Resolving all 158 open errors through the celigo CLI…); one action at a time per canvas. After a completed action the list is read again — resolved errors leave it — the overlay is re-read so the step's count and the toolbar badge follow, and the payloads cached for the step's errors are dropped.

A retry takes retryDataKeys, not errorIds. The panel keeps naming errors by id and the host resolves the keys from a fresh listing, the way the CLI's own flows error does, refusing an id no longer listed (refresh the list) and an error without retry data (resolve it instead) before anything is written; the webview never holds a key, and no record, request, or response reaches a log, a modal, a command line, or a note — ids and the CLI's lines only. Every button is disabled with its reason in Restricted Mode and without the CLI, as the list itself is. Assignment, comments, tags, and the resolved-error history stay in Error Management. See flows for errors, error, retry-errors, and resolve-errors.

Restricted Mode

The extension has limited support for untrusted workspaces. In Restricted Mode the canvas renders, the details panel and the JSON editor work, and edits are written to the open document. Nothing spawns the celigo CLI: lint findings, the live overlay (its timed refresh included), the Live errors list and its Retry / Resolve, Pull latest, push, and the npx offer stay off until you trust the workspace, and Live, Push, and every disabled button say so in their tooltips. When you trust the workspace, open canvases refresh on their own.

⚠️ celigo.cliPath is a restricted setting. A workspace's own value is ignored until you trust the workspace, so an untrusted folder cannot choose the executable the extension runs.

In a virtual workspace, rendering works on any JSON document. Tree lookups, the CLI, and file edits need a local folder.

Settings

Setting	Default	What it does
celigo.cliPath	celigo	The CLI executable the extension runs for lint findings, the live overlay, and push. Leave it as celigo to use the one on your PATH, or set the path to the executable. When none is installed, the extension offers to run the CLI through npx; accepting writes npx --yes @celigo/celigo-cli@<version> here, in your user settings. Restricted setting: a workspace's own value is ignored until the workspace is trusted.
celigo.canvas.lint	true	Run celigo lint on the open document and show the findings on the steps they concern. Needs the CLI.
celigo.canvas.liveOverlay	false	Overlay live account state — open-error counts per step, enabled or disabled on the server and the last run, whether the server copy changed since the pull — read from the account the tree is bound to, through the CLI in read mode. The overlay writes nothing; the Live errors list's Retry / Resolve are the canvas's only account writes, and each is an explicit click.
celigo.canvas.liveRefreshSeconds	60	How often the live overlay is re-read while its canvas is visible and the window focused, in seconds — the same read-mode CLI reads as the Live button. 0 turns the timer off: the overlay then refreshes only on demand (the Live button, a save, Celigo: Refresh Live Overlay). Values below 15 are raised to 15. After a failed read the wait doubles, up to 10 minutes, until a read succeeds. Added in extension 1.1.0.
celigo.canvas.showComponents	true	Show the step component chips (filters, mappings, hooks, error handling) on step cards.
celigo.canvas.direction	horizontal	Lay the canvas out left to right (horizontal, as Flow Builder does) or top to bottom (vertical). View › Vertical layout flips one canvas without changing the setting; a changed setting takes over again. Celigo: Copy Flow as Mermaid follows the canvas.

Commands and keybindings

Command	ID	Keybinding	Where
Celigo: Open Flow Canvas	celigo.open	—	Command Palette; the editor's context menu on a flow document; the Explorer's context menu on flow.json, tool.json, and api.json. Opens the canvas in the current editor group.
Celigo: Open Flow Canvas to the Side	celigo.openToSide	Cmd/Ctrl+Shift+V while the editor has focus on a flow document	Command Palette; the preview icon in the editor title. Opens the canvas beside the editor.
Celigo: Copy Flow as Mermaid	celigo.copyMermaid	—	Command Palette while a flow document is active. The toolbar's Export › Copy Mermaid diagram does the same.
Celigo: Push Flow with celigo (plan first)	celigo.push	—	Command Palette while a flow document is active. The toolbar's Push does the same.
Celigo: Refresh Live Overlay	celigo.refreshLive	—	Command Palette. The toolbar's Live button does the same.
Celigo: Apply the JSON Panel's Edits	celigo.applyJson	Cmd/Ctrl+S while a canvas is the active editor	Command Palette while a canvas is the active editor. The details panel's Apply does the same.
Celigo: Find Node on the Canvas	celigo.findNode	Cmd/Ctrl+F while a canvas is the active editor	Command Palette while a canvas is the active editor. Focuses Find node in the toolbar.
Celigo: Show or Hide the Details Panel	celigo.togglePanel	Cmd/Ctrl+\ while a canvas is the active editor	Command Palette while a canvas is the active editor. The chevron in the details panel's header and View › Show details panel do the same. Added in extension 1.1.0.

The last three commands exist for their keybindings. They apply while a canvas is the active editor, wherever focus sits inside it, and can be rebound in Keyboard Shortcuts. Cmd/Ctrl+\ is Split Editor's key, which a webview panel has no use for; it is taken over only there.

Troubleshooting

The canvas asks for a window reload

A VSIX reinstalled at the same version overwrites the extension in place. A canvas opened afterwards would run the updated webview against the still-running old extension host, so the host stamps a protocol revision on every graph and the canvas shows a banner when the two differ. Run Developer: Reload Window from the Command Palette.

celigo is not found

Lint findings, the live overlay, and push need the CLI. Install it, or point celigo.cliPath at the executable:

npm install -g @celigo/celigo-cli
celigo --version

When no celigo answers, the extension offers once per session to run it through npx, pinned to the CLI version it needs. On Windows, the npm-installed celigo is a .cmd shim; the extension runs it through cmd.exe, and a tree path with spaces or parentheses arrives intact. For celigo: command not found in a terminal, see Troubleshooting.

Lint findings, the live overlay, or push are off

Live and Push say why in their tooltips. Either the workspace is in Restricted Mode — trust it, and open canvases refresh on their own — or the CLI is missing.

Push met an unsaved buffer

Push sends what is on disk. Since extension 1.1.0 the Push button asks — flow.json has unsaved edits. Push sends what is on disk. — and Save all and continue saves the document and every named related buffer before the terminal opens; Cancel leaves everything as it is. A save the editor could not make stops the push (Push did not run: … could not be saved): fix what the editor reports, save, and push again.

Retry or Resolve shows a read-mode refusal

The tree's profile is in read mode, so the CLI refused the write before any request left your machine — Read mode: blocked POST v1/flows/…. Switch with 'celigo config set mode operate' (or 'full'), or use a different profile. The extension never overrides a profile's mode. Follow the hint in a terminal — celigo config set mode operate (or full) on that profile, or use a profile whose mode allows the action — then run the action again. See Permission modes.

remote changed shows when nothing changed

Extension 1.0.0 called the server copy remote changed whenever its lastModified differed from the pulled token, and the platform bumps that token for a flow run or a debug toggle. Since 1.1.0 the badge means celigo diff reported differences; a moved timestamp with matching content is a timestamp moved drift with no badge. If the Drift row says the content was not compared, the diff itself failed — the row quotes the CLI's reason and the celigo diff line to run yourself.

A panel request stalls

Every request the details panel makes resolves to content, a note, or an error line within 8 seconds. A stalled request says so instead of loading forever, and points at a window reload. While a modal waits for your answer — a Resolve all, a Pull latest on a document with local edits — the panel says so in a muted line and the stalled note stays off; a pull has ten minutes rather than eight seconds, under a progress notification.

Get help

For extension bugs and feature requests, contact Celigo Support with the extension's version, your VS Code or Cursor version and operating system, the output of celigo --version when the CLI is involved, and a minimal reproduction. Never post API tokens, credentials, customer data, or complete request or response payloads. For failures on the CLI's side — 401 Unauthorized, celigo: command not found — see Troubleshooting; for a refused push, see push.

What's next

• The local tree — pull, status, diff, and push for the tree the canvas opens.

• push — the plan, the check against the server copy, and --prune.

• flows graph — the same graph from the terminal, as JSON, Mermaid, or DOT.

• AI assistant skills — give your AI coding assistant grounded knowledge of integrator.io for editing the tree.