GuideWorkflows
Building workflows in CSuite.
Every node, handle, setting and run rule on the workflow canvas, with a figure for each, followed by recipes that chain models into repeatable jobs. The short version lives on the main guide; this page is for when you want to know exactly what a node does.
Part 1
Get around
1.1
The canvas
Open Workflows from the rail, the last entry of the second group. A workflow is a graph you draw: inputs on the left, models and edits in the middle, files on the right. Connect the dots, press Run, and run it again whenever the inputs change. The canvas is the whole programming model.
- 1 · Workflows list
- Your project folder pill, the + for a new workflow, and every workflow with its node count. A row’s More actions offers Duplicate, Export, Save as template and Delete.
- 2 · Toolbar
- The name (edit in place), Undo and Redo, Add Node, Auto arrange and the Assistant toggle.
- 3 · Stop and Run
- Run executes the whole graph; Stop appears while a run is in flight. Hover Run for a cost estimate or the reason it is disabled.
- 4 · Models
- The global model slots, including the Chat model the assistant thinks with. A new Model node starts on the slot for its modality.
- 5 · Canvas
- Nodes on a dotted grid with typed, coloured handles and edges. Drag to pan, scroll to zoom, drag a marquee to select several.
- 6 · Controls and minimap
- Zoom in, zoom out, fit view and a lock, plus a minimap with nodes filled by kind.
- 7 · Assistant
- Describe a workflow or a change in plain language; the graph edits land as one undo step.
Everything saves about half a second after each change. Undo covers edits (adding, wiring, settings, a finished drag) up to fifty steps; a run never adds a step.
1.2
Creating one
- Create opens a blank canvas named “Untitled workflow” (the assistant renames it after your first request, or type a name in the toolbar). The hint says “Pick a node from Add Node in the toolbar, or press M to start with a model.”
- Templates opens a picker of ready-made graphs; see Templates. Your very first workflow arrives pre-built as Input → Model → File so you see the shape.
- Import opens a workflow JSON file someone shared; see Sharing and Chat.
- The + is disabled until a project folder is set. Delete on a row removes the workflow; files its File nodes saved stay in your project.
1.3
The ten node kinds
- Input: a typed prompt (with
{{variables}}) or attached image, audio or video files. - Model: runs an AI model of any modality on what is wired into it, and shows a thumb of its result.
- Edit: a deterministic transform on files, fanned out across every input.
- Combine: merges several files into one, in parallel or in series.
- Switch: you pick which of several inputs flows on.
- Decide: a model picks, given a question.
- Bulk: starts a batch from a folder, a CSV or Input nodes; everything after it runs once per row.
- Preview: shows what flows through, saves nothing.
- File: saves the result into your project folder.
- Note: a label on the canvas; no inputs, no outputs, never runs.
Add one from Add Node or with a single key while the canvas is focused: I M E C S D B V F N. Each node header has Duplicate node and Delete node; hover the label for its description.
Part 2
Build
2.1
Connecting nodes
- Handles: inputs on a node’s left edge, outputs on its right, coloured by content type (text, image, audio, video). Hover a node to see its port labels; while you drag a connection every node shows the side you can land on.
- Drag from an output dot to an input dot. A mismatched type, a loop, or a node connected to itself is refused. Release over empty canvas and a palette offers Model, Edit, File or Preview (or Input, Model, Edit from an input dot), created and wired on pick.
- Several into one: a Model’s prompt handle takes several text edges (joined with new lines); media handles take several files; Combine, Switch and Decide grow a free in N slot after the last connected one.
- Tidy: nodes snap to the dot grid and, when dragged, into line with the handles they connect to, so edges land straight. Auto arrange lays the whole graph out left to right and re-fits the view; Notes stay put.
- Select with a click or a marquee; Delete removes the selection and any edge left dangling; Esc deselects.
2.2
The Model node
- Modality: Text, Image, Audio or Video. Audio adds a Type (Music, Sound Effects, Text to Speech). Changing either clears the model and the edges that no longer fit.
- Model: one list grouped by provider, with Auto — best model for the prompt first, cloud providers in catalog order, then Ollama, Hugging Face and GGML as “(local)”. A new node starts on your global slot for its modality. A saved model that has since been hidden stays listed as “(saved — hidden)”.
- Handles follow the model: prompt and instructions (text or a text file), then an image, video or audio handle for each kind the model reads. A video model that takes frames shows start frame and end frame instead of a plain image handle; a vision-capable local model shows an image handle too.
- Settings: the model’s own parameters under an accordion, the same ones the workspaces show (aspect ratio, duration, resolution, voice, reasoning depth); local models have none.
- After a run the header chip reads Done and its tooltip the time and cost (“3.2s · $0.04”). A small thumb of the result shows on the node unless a File or Preview node further down already shows it.
- Run on the node runs from here to the next Model node, so you can iterate on one stage without re-paying for the stages above.
2.3
Prompt variables
Write {{name}} anywhere in a text Input’s prompt and the node grows an input handle by that name, with a chip under the box that lights up once something is connected. At run time the connected text (a model’s reply, another Input’s prompt, a text file, a CSV column) is substituted in, so one prompt template serves many inputs. Names are letters, digits, hyphens and underscores; the same name used twice is one handle. A variable with nothing connected blocks the run, so braces never reach a model by accident. Retyping the node’s input type clears the prompt and its variable edges.
2.4
Edit and Combine
- Edit runs one Operation on every file wired in, in parallel, on your machine. Images: Resize, Crop, Format. Audio: Trim, Volume, Fade, Format. Video: Resize, Crop, Trim, Speed, Mute, Format, Extract audio, Extract frame (first or last). Image and video: Text overlay at one of nine positions. Once an input is connected only its bucket is offered. The two extract operations change the type that flows on, so a video branch can feed an audio or image branch.
- Combine merges every file on its in N handles. Parallel plays them together: video plus audio makes a video with that soundtrack, image plus audio makes a video, several audio tracks mix. Series concatenates them in handle order. It needs at least two inputs, except when one of them carries a batch.
- Edit and Combine cost nothing to run and can be stopped mid-way like a model. A failed file cancels that Edit’s siblings; other nodes keep going.
2.5
Switch and Decide
- Switch is an A/B selector you operate: wire several alternatives in, pick one in the radio row (with a thumbnail once it has run), and only that one flows on. Swap the pick without rewiring. If the picked input is disconnected it falls back to the first.
- Decide lets a model pick. Wire a question (“Which one shows the whole product?”) and two or more candidates of one type, each carrying exactly one item. A text model (Auto by default) sees them numbered and names one, with a reason; a Decision model judges text candidates, or images where it reads them, for up to 26 and reports its confidence (“Chosen with 92% probability.”). An unreadable answer errors the node rather than guessing. Every candidate branch still runs; the pick is remembered on partial re-runs and asked again when the node is in the segment.
2.6
Preview, File and Note
- Preview shows whatever flows through it, live from its sources, and passes it on unchanged. Several items (a multi-file Input, an Edit fan-out) get a 1 / N stepper; text renders as Markdown with Copy text, images with Copy image. Drag its corner to size it. Nothing is saved.
- File saves exactly one upstream file into your project folder, named after its source and the edits it went through (“shoe-crop-4-3.png”), with the model and prompt attached so the Info popover and Use prompt & settings work there. Several File nodes on one source each take one item by their vertical order. A text result is editable right on the node and writes back to the file. Double-click the output to show the file in the folder. Everything between nodes lives in a scratch space; only what a File node claims lands in the project.
- Note: free text with alignment and font size, for labelling sections. No handles, never runs.
Part 3
Run
3.1
Running and run-from
- Run executes the whole graph. Independent branches run at the same time; only a node’s direct predecessors serialise it, and at most five generations run at once. Each node shows Queued, Running, Done or Error in its header, and edges into a running node march.
- Run on a node runs a segment: from that node to the next Model node (from an Edit, also to the next Edit). Nodes outside the segment replay their last result, so a source that never ran fails with “Run the earlier nodes first”. Everything downstream of the start is reset, since its result came from the output being replaced.
- Stop cancels every in-flight call on the provider too, frees a local GPU, and drops the nodes back to idle. A finished node keeps its result.
- Failure: the node keeps its error with Retry from this node; its dependents are skipped rather than fed nothing, and other branches finish.
- When it ends, an OS notification names the workflow and the cost (“Product shot, 4 styles — $0.16”), or how many nodes failed.
3.2
Validation and cost
The graph is checked on every change. A node that cannot succeed gets a warning badge with the reason, and Run is disabled with “n nodes need setup”: no model picked or nothing connected (Model), no operation or no input (Edit), fewer than two inputs (Combine, Decide), an empty prompt or an unconnected variable (Input), a media Input with no files, mixed types on a Preview or Decide, a candidate carrying several files, a model that cannot read the candidate type, a Bulk node with no folder or CSV, rows from two Bulk nodes meeting, or a loop. Per-node Run is gated the same way on that node and its ancestors, so a half-built branch elsewhere never blocks a ready one.
Hovering Run shows a rough cost for one full pass, summed from catalog prices over the cloud Model nodes with nominal quantities (one image, the node’s duration, a short text reply); a node inside a batch is counted once per row. Under Auto the model is chosen at run time, so nothing is estimated for it. Real costs come back per node after the run.
3.3
Bulk over a folder
1
Point it at a folder
Set What to read to images, videos, audio files or text files in a folder and press Choose folder. The node counts the files of that type directly in the folder (no subfolders), read in name order. The folder can be anywhere; outside files are copied into the project once and reused.
2
Wire it like one file
Its output carries every row. Wire it into a Model’s image handle, an Edit, a Decide: every node after it runs once per row, and the status chip reads “7 / 10” while it does. Several files wired into a Model without a Bulk node still go into one call as references.
3
Choose how it runs
Run mode: Sequential (one at a time), Parallel (multiple at a time), or Single (for testing out) to try the first row only. Limit caps a run at 25 rows by default, up to 500, so a large folder cannot surprise you.
4
Save and retry
A File node saves one result per row, named after the source file plus what was done (“The Last-edit-crop-4-3.jpg”), stepped through from a pager under the node. A Combine node gathers every row into one file instead. A failed row does not stop the rest; Run the rows that have no result yet retries only the missing ones, and Stop keeps the rows already done.
Each run reads the folder again from the top, so new files are picked up and earlier rows run again. Rows from two Bulk nodes cannot meet in one node, and a Bulk node cannot feed another. An Input node source turns the files or texts wired into the Bulk node into rows.
3.4
Bulk over a CSV
Set What to read to Rows of CSV file and Choose CSV file. The first line is the header and every column becomes its own output handle. A column whose cells all name files of one kind (relative to the CSV’s folder, or full paths) sends that file; any other column sends its text. Wire a text column into a {{variable}} or straight into a Model’s prompt and every row gets its own prompt. Name results by picks the column that names a row’s saved files. Comma, semicolon and tab delimiters are detected, with UTF-8, UTF-16 and Windows-1252 text, up to 12 columns and 10 MB. A missing file is reported by spreadsheet row before anything runs, and a column the file no longer has fails the node until you choose it again.
Part 4
Reuse
4.1
The assistant
Press Assistant in the toolbar for a panel beside the canvas. Describe a workflow to build (“generate a product photo and turn it into a short video”) or a change to the one you have (“add a model node that writes a caption”, “connect the image to the video model”, “branch this into 16:9 and 9:16”). It adds, removes, configures and connects nodes, places them, and lands the whole edit as one undo step with an “n changes applied · ⌘Z undoes” footer; an operation the graph cannot take is listed as skipped. It names an untitled workflow after what you asked. It runs on your Chat model (set it in the Models popover; with none, the composer says so), sees your graph with the models named by token, and can add and configure a Bulk node, though you pick the folder or CSV yourself and those paths are never sent. The conversation is saved with the workflow.
TipTell it the subject, not the job: an Input node’s text goes to the model verbatim, so “a monkey eating a banana, documentary style” works and “a prompt that generates a product photo” does not.
4.2
Templates
- Built-ins: Text to image (the Default), Image to video with music, Product shot, 4 styles, Product mockups in bulk, Bulk image edit and Podcast intro. Picking one creates a new workflow from it; a Bulk template still needs its folder chosen, and a Model node lands on your configured provider or asks you to pick.
- Yours: Save as template on a workflow’s row snapshots the graph (run results stripped) into your list with a Yours badge and an inline delete. Duplicate copies a workflow outright instead.
Part 5
Recipes
5.1
One subject, four styles
1
Start from the template
Templates → Product shot, 4 styles. One subject Input fans into four style Inputs, each with a
{{subject}} variable, into four image Models.2
Change one thing
Edit the subject Input once; every branch picks it up. Swap a style line, or set one branch’s Model to a different provider to compare.
3
Pick and save
Wire the four outputs into a Switch to choose by eye, or a Decide with “which looks most like a catalogue photo?”, then a File node. Run; hover Run first to see the cost of four generations.
5.2
Blog post to voiced video
1
Text in, script out
An Input with the post’s text feeds a text Model whose instructions say “Write a 60-word narration script”. A Preview after it lets you read the script before anything is billed.
2
Voice and picture
The script feeds an audio Model (Text to Speech) and, through a second text Model that writes an image prompt, an image Model. A video Model with a start frame handle animates the image.
3
Combine and save
Video and voice into a parallel Combine, an Edit → Text overlay for the title, then a File node. Run from the voice Model alone when you only re-record the narration.
5.3
Mockups for a whole folder
1
Use the template
Templates → Product mockups in bulk, then Choose folder on the Bulk node and write the scene in the Input (“on a walnut counter in morning light”).
2
Test on one
Set Run mode to Single, run, check the File node’s result, adjust the prompt.
3
Run the batch
Switch to Parallel, set a Limit you are happy to pay for, and run. Each result is saved under its photo’s name; retry the missing rows if any failed.
5.4
A campaign from a spreadsheet
1
Make the sheet
Columns
product, photo (a path beside the CSV) and tagline, one row per item, saved as CSV.2
Wire the columns
Bulk → Rows of CSV file. The
product column into a {{product}} variable on the prompt Input, the photo column into the Model’s image handle, the tagline column into an Edit → Text overlay after it. Name results by product.3
Run and collect
Run with a Limit. The File node holds one named image per row; a Combine in series would instead stitch them into one clip.
5.5
Compare, then let a model pick
1
Fan out
One prompt into two or three image Models on different providers or settings.
2
Judge
All of them into a Decide with a question Input (“Which one has the correct number of fingers and a clean background?”), on Auto or a Decision model that reads images. The body shows the winner and the reason.
3
Keep a manual override
Put a Switch after the Decide alongside the raw branches when you want to overrule it, then a File node.
5.6
A podcast intro, repeatable
1
Template, then your words
Templates → Podcast intro: a Text to Speech Model for the spoken intro, a music Model for the sting, mixed by a parallel Combine. Put the episode line in the speech Input as
{{episode}} with a second Input feeding it.2
Shape the sting
Add Edit → Fade and Edit → Volume on the music branch so it sits under the voice.
3
Run it every week
Save as template, or keep the workflow and ask Chat to “run my podcast intro workflow” after changing the episode line; the mixed file lands in the Audio workspace.
Part 6
Reference
6.1
Keyboard shortcuts
⌘ is Ctrl on Windows and Linux. Keys work while the canvas is focused and you are not typing in a field. The main guide lists every workspace’s shortcuts together.
Add a node
I / M / E / C- Input, Model, Edit, Combine
S / D / B- Switch, Decide, Bulk
V / F / N- Preview, File, Note
Edit the graph
⌘Z / ⌘⇧Z- Undo and redo (⌘Y also redoes)
Delete / Backspace- Remove the selected nodes and edges
Esc- Deselect
Scroll / drag- Zoom and pan the canvas
Assistant
Enter / Shift+Enter- Send a message / add a line
6.2
Troubleshooting
- Run is disabled: “n nodes need setup”. Find the badged nodes; each badge names its issue (“Choose a model”, “Connect a prompt”, “Enter prompt text”, “Choose an edit operation”, “Connect at least 2 inputs”).
- “Connect or remove {{topic}}”. A variable has nothing wired into its handle; connect a text source or delete the braces.
- “Part of a cycle”. An imported graph loops; remove the looping connection.
- “Run the earlier nodes first”. A node’s source outside the run segment has never run; run the full graph once, or run from that source.
- A connection is refused. The types differ (an image output into a prompt handle), it would loop, or the handle is taken (a Decide has one question). Check the handle colours.
- “This model can’t read image inputs.” The Decide’s or Model’s picked model takes no images; pick one that does, or Auto.
- “The model didn’t name one of the inputs.” Decide could not parse the reply; rephrase the question or pick a stronger model. There is no silent fallback.
- “Input 2 carries 3 files, Decide takes one per input.” Each candidate must be a single item; put a Switch or a single-file Input in front.
- “Choose a folder” / “Choose a CSV file”. The Bulk node has no source yet, or the file could not be read (“This folder could not be read.”).
- “Rows from two Bulk nodes cannot meet in one node.” Connect only one Bulk node into that path, and never one Bulk node into another.
- “Combine needs at least 2 files, and this run sent one row.” The Bulk node is in Single mode; switch to Sequential or Parallel.
- “The CSV file no longer has a … column.” The header changed; choose the file again and rewire the column.
- Rows failed: 2 of 10. The chip’s tooltip lists them; Run the rows that have no result yet retries just those.
- The assistant is disabled. “Pick a Chat model from the Models menu in the toolbar to enable the assistant.” Under Auto, “Auto couldn’t pick a model” means no tool-capable provider is set.
- “Skipped n changes: unknown model”. The assistant referenced a model it does not have; pick it by hand on the node.
- An imported workflow’s Model nodes show no model. You have no provider of the kind the export used; add one under AI model providers or pick another model.
- Results vanished after switching project folder. By design: outputs belong to the old folder, so run states are cleared. The saved files are still in that folder.
- “Couldn’t open this workflow — its saved layout appears to be corrupted.” Import the exported JSON again, or duplicate a template and rebuild; a corrupted workflow also refuses to run from Chat.