Workflows
A workflow is a trigger plus a tree of steps that runs on your device, over a shared context. This page covers every screen of the module, the 25 triggers, the 15 actions, the seven kinds of step, expressions, scheduling, secrets, sharing, and what Free and Pro each get.
What it is and how to open it
Workflows is a full-screen window that opens over the app, not one of the five pages of the pager. A workflow is saved on your device and runs there: one main trigger (plus up to five more) and a tree of steps of seven kinds. Scheduled runs go through Android's WorkManager; while any run is alive PocketCode keeps a notification with a Stop button.
Ways to open it
| Where you are | What you tap | What opens |
|---|---|---|
| The Tools sheet of the navigation bar | Workflows, in the second row of cells | The module, on its welcome screen |
| The side menu | Workflows, in the tools category | The module |
| Home | Any row of the Workflow runs widget (the widget only draws when there are runs) | The module |
| A run notification, or the notice of a scheduled workflow that could not start | Tap it | The detail of that run, or the editor of that workflow |
| The activity panel of the AI chat | A row for a workflow run | The module |
| Outside the app | A link: pocketcode://workflows, pocketcode://workflows/run/<runId>, pocketcode://workflows/<workflowId> or pocketcode://workflows/import?url=<https address> | The module, that run, that workflow, or the import sheet. A link only opens a screen: it never runs, deletes or downloads anything by itself |
How the window behaves
- The module is its own window, so you can't see the rest of the app while it is open. Back goes one level up: editor to list, run detail to the history or the tabs, secrets to the tabs, the tabs to the welcome screen, and the welcome screen closes the module.
- On a wide window (840 dp wide and 480 dp tall or more, such as a tablet) the list stays on the left and the editor, history or run detail opens on the right. The step settings panel (360 dp wide) is only used when the editor keeps at least 400 dp beside it; otherwise step settings open as a sheet.
- A workflow can also be started without opening the module: from a home screen shortcut, a Quick Settings tile or the system Share menu (see Running and watching).

You can't, and why
- Open it from the command palette: the palette has no Workflows command, and Workflows is not a page of the pager either.By design
Screen map
One row per screen, sheet and dialog of the module, and where it comes from.
| Screen | How you get there | What you can do |
|---|---|---|
| Welcome screen | Opening the module; Back from the tabs | Open My Workflows, Generate from prompt (portrait only), Templates or CI / CD (both open the Templates tab). |
| Header and tabs | Always on top | Switch between My Workflows, Templates and Activity. On the first tab only: Import a workflow from a file, Manage secrets and the + button (New workflow). The banner Scheduled workflows need attention shows above the tabs when something would hold scheduled runs back. |
| My Workflows tab | First tab | Search, sort and filter by tag; switch a workflow on or off; run, stop, schedule, open its history, delete; open the long-press menu. |
| Tags dialog | Tags in a card's menu | Add or remove up to 8 tags on a workflow. |
| Templates tab | Second tab; the Templates and CI / CD cards of the welcome screen | Search the 17 templates, filter by family, open a preview, Activate or Add another copy. |
| Template preview | Tap a template card | Read Starts when, the steps, What it needs, and run a dry run (Test now) that touches nothing. |
| Activity tab | Third tab | See the latest runs of every workflow; search in the errors; filter by status, date and workflow; stop a live run; open a run; copy the filtered runs as JSON; Delete history. |
| Editor | Tap a card, Edit in its menu, the + button, a notice of a scheduled workflow, Open in editor | Name it; declare Inputs; set Workflow settings and Permissions; choose triggers and filters; build the step tree; test; save. |
| Step settings (seven sheets) | The pencil of a step, or Add step | Configure an action, If / Else, Loop, In parallel, Try / on failure, Subflow or Wait. On an action, also Reliability and Conditional. |
| Add step palette | The + button of the editor, or the + of a branch | Search the 15 actions and the six control-flow blocks by name, description or output; use favourites and recents. |
| Insert data picker | The button of the same name in a parameter | Pick an input, a trigger field, an earlier step's output or status, or the item or error of the block you are in. |
| Problems panel | Inside the editor, above the steps | Read errors, warnings and tips and jump to the step with Go to step. |
| Convert to subflow dialog | Turn into a subflow in a step's menu | Name the new workflow and move the step and its contents into it. |
| Run dialog (run inputs) | Run now on a workflow with required inputs; Run with these inputs in a run | Fill the declared inputs (defaults already in) and press Run. |
| Run history | Run history on a card or in its menu | See one workflow's runs; Stop this run; open a run. |
| Run detail | A run in the history or in Activity; a notification; a deep link | Read every step (result, duration, attempts, error, JSON output), follow the live shell log, Run again, Repeat from the failed step, Run with these inputs, Analyse with AI, Copy as JSON. |
| Repeat this run dialog | Run again or Repeat from the failed step | Read what changed since that run before confirming. |
| Schedule sheet (Schedules for …) | Schedule on a card or in its menu | List and remove schedules; add presets or Custom cron; set Device conditions and If a run is missed. |
| Secrets | Manage secrets (key icon) | Add, change the value of, or delete encrypted secrets; see which workflows use one before deleting it. |
| Share this workflow sheet | Share as file in a card's menu | Check which secret fields are emptied and share the .pcwf.json file. |
| Import workflow sheet | Import a workflow from a file | Preview a file (trigger, steps, missing secrets, linter result) and save it switched off. |
| A link wants to import a workflow | A pocketcode://workflows/import?url=… link | See the address it comes from and choose Download or No thanks. |
| Generate workflow from prompt and Change … with AI | Generate from prompt on the welcome screen; Change with AI in a card's menu | Describe an automation or a change, review the result, Save & enable or Open in editor. |
| Irreversible-steps dialogs | Switching on a workflow with irreversible steps; saving one that is Available to AI agent | Read the steps and decide: Enable anyway or Allow the AI. |
| Shortcut, tile and Send to a workflow | The home screen, Quick Settings and the Android Share menu | Start a workflow without opening the module. |
| Run notification | The notification shade while a run is alive | Follow Step n of m and press Stop. |
The list, tags and templates
The module has three tabs, My Workflows, Templates and Activity (the last one is covered under Running and watching). Above the tabs, on My Workflows only, sit Import a workflow from a file, Manage secrets and the + button (New workflow), which opens the editor with an empty workflow that is switched off and has the Manual or scheduled trigger.
Welcome screen
The module always opens here. Back from the tabs returns here; Back from here closes the module.
You can
- Tap My Workflows (Manage your active automations) to open the list.
- Tap Generate from prompt to describe an automation in a sentence (see AI: generate, change and the chat). The card is only there in portrait.
- Under Explore, tap Templates or CI / CD. Both open the same Templates tab: CI / CD doesn't filter anything.
You can't, and why
- Create a blank workflow from here: use the + button on My Workflows.By design
- See Generate from prompt in landscape (a phone on its side, a tablet held sideways): the landscape welcome screen has only My Workflows, Templates and CI / CD. Change with AI in a card's menu still works.Not yet
My Workflows tab
One card per workflow, with its status, when it last ran, health dots and, if it is scheduled, the next run.

You can
- Search your workflows: it looks in the name, the description and the tags, ignoring accents.
- Sort by Recently edited, By name, Last run or Problems first.
- Filter by tag with the chips (All plus your tags, most used first).
- Switch a workflow on or off with the switch on its card. Switching one on that has irreversible steps asks once (see Running and watching).
- Tap the ▶ icon to run a workflow whose main trigger is Manual or scheduled; while it runs the icon becomes a ■ Stop with a progress ring, for any workflow, whatever started the run.
- Use the clock icon (Schedule), the history icon (Run history) and the red bin (delete).
- Delete a workflow with the red bin or with Delete in the card's menu. A dialog asks Delete “<name>”? (“The workflow and its schedules are removed. This cannot be undone.”) and removes it only when you tap Delete; Cancel leaves everything as it was.
- Long-press a card, or use a secondary click, to open its menu.
You can't, and why
- Have a ▶ on the card of a workflow that starts from an event or a shortcut: for those, Run now is in the card's menu.By design
- Keep the search, the sort or the tag filter when you leave the screen: a filter hides things, so it is asked for again every time.By design

What a card shows
| Part | What it tells you |
|---|---|
| Status | Idle, Running, Completed, Failed or Cancelled, and Last run: (or Never run). |
| Health | Dots for the last 5 runs and the success rate (for example 100% success); No finished runs yet when there is none. |
| Trigger | The label of the main trigger, such as On git push or Manual or scheduled. |
| Next: | The next scheduled run, if the workflow has a schedule. |
| Live progress | Step n of m while it runs. |
The card menu
| Item | What it does |
|---|---|
| Edit | Opens the editor. |
| Change with AI | Opens the change sheet (see AI: generate, change and the chat). |
| Activate / Deactivate | The same as the switch. |
| Run now / Stop | Starts a run of any workflow, whatever its trigger; with required inputs it asks for them first. While a run is going the item is Stop. |
| Schedule | Opens the schedule sheet. |
| Run history | Opens that workflow's runs. |
| Duplicate | Makes a copy that is switched off, with new step ids and copy after its name. |
| Share as file | Opens the sheet that exports a .pcwf.json. |
| Tags | Opens the tags dialog. |
| Delete | Asks Delete “<name>”? and, once you confirm, deletes the workflow and its schedules. |
Tags
Tags group the list without moving anything. They live in the workflow's settings, so they travel in the exported file.
You can
- Open Tags from a card's menu, type in New tag and add it; remove a tag from the same dialog.
- Filter My Workflows by tag; the chips are ordered by how many workflows use them.
You can't, and why
- Put more than 8 tags on a workflow (8 tags is the limit.): twenty tags organise nothing.By design
Templates tab
17 ready-made workflows, grouped by what starts them. Each card shows its name, a description, its trigger, the kinds of action it uses and What it needs: irreversible steps, terminal commands, a connected deploy provider, an AI provider with a key, the network, writing files, an open project.
You can
- Search templates by name, description, trigger or action; filter by family with the chips (All and the six families below).
- Tap Activate to get an editable copy with a new id that is switched on and appears in My Workflows; tap Add another copy if you already have it. The copy does not share anything with the template.
- Open the preview, run a dry run, and edit the copy afterwards in the editor.
You can't, and why
- Edit a template in the gallery: you edit your copy. The catalogue is fixed at 17 templates.By design
- Be asked about irreversible steps when you press Activate: the question only appears when you move the switch of a workflow later. Read What it needs before you activate.Not yet

The six families
| Family | What it contains |
|---|---|
| When you edit | 3 templates, all of them starting from On file save. The family also holds anything that starts from a file being created, deleted or renamed, or changed by the AI. |
| When you use git | 5 templates: three start from On git push and two from On git commit. |
| Around a deploy | 1 template, which starts from Deploy completed. The family also covers Deploy failed. |
| When something breaks | 1 template, which starts from An error was detected. The family also covers a build or a run finishing. |
| From your phone | 1 template, which starts from Text shared to PocketCode. The family also covers the home screen shortcut, the Quick Settings tile and shared files. |
| On demand, or on a schedule | 6 templates that start with Manual or scheduled: you run them, or you add a schedule from the clock button. |
The 17 templates
| Template | Starts when | What it does and what it needs |
|---|---|---|
| Prettier on Save | On file save, for .js files | Runs prettier --write on the file you just saved, not on the whole project. |
| Auto-Commit on Kotlin Save | On file save, for .kt files | Commits only the saved file, on the checked-out branch, and does not push. Saving with no real change is not a failure. |
| Lint the File You Just Saved | On file save, for .ts files | Waits two seconds, runs eslint on that file and notifies only if it finds something. Saving again while it waits cancels the pending run. |
| Tests, then Deploy if they pass | On git push | Runs the test command, and asks for a deploy only when it exits with 0; otherwise it notifies and deploys nothing. Needs a deploy provider connected in the Backend Manager. |
| Auto-Deploy on Push to main | On git push, filter main | Deploys after a push to main and notifies with the status and URL. |
| Tests after Push to main | On git push, filter main | Runs the test suite after a push to main and notifies with its exit code (it cannot block the push). |
| Test on Commit | On git commit | Runs the tests after a commit and notifies with the exit code and the message. It only fires for commits made from Projects. |
| Test Every Module You Touched | On git commit | A loop over the directories of the commit (up to 20) that runs the test command once per directory; a failing module does not stop the rest. Same limit as above: only commits made from Projects. |
| DB Backup after Deploy | Deploy completed | Runs a pg_dump and reports the file; edit the command for your own database. |
| AI Analysis of a Failed Workflow | An error was detected | Sends the error to the AI and notifies with the answer. Needs an AI provider with a key. The card says it only sees workflow failures; today the trigger also hears editor build and run errors and failing terminal commands run by the AI. |
| Nightly Backup | Manual or scheduled | Dumps your database into a folder of the project and tells you only when it fails. Attach a schedule (for example Daily at 9:00) from the clock button: a schedule is not a trigger. |
| Test a Branch You Pick | Manual or scheduled | Asks for a branch (default main), checks it out in the open project and runs the tests. It changes your working tree: commit or stash first. |
| Release Notes from the Last Commits | Manual or scheduled | Reads the last 20 commits, asks the AI for release notes and writes RELEASE_NOTES.md, overwriting it. Needs an AI provider. |
| Check an Endpoint | Manual or scheduled | A GET request and a notification with the status code and the time. The URL has a default, so it can run unattended once you set yours. |
| Check Three Endpoints at Once | Manual or scheduled | Asks for three URLs and calls them in parallel, waiting for all three. Open the run to see each status code. |
| Deploy, and Tell Me Even If It Fails | Manual or scheduled | A Try / on failure around a deploy that notifies either way. Needs a deploy provider connected. |
| Save a Shared Link to links.md | Text shared to PocketCode | Appends a page shared from any app to links.md in the open project, never overwriting it. |
Template ids never change, so a workflow created from one keeps its link to its template.
Template preview
Tap a template card to see what it would do before you activate it.
You can
- Read Starts when, the step tree with its branches (If it matches, Otherwise, Try this, If it fails) and What it needs.
- Run a dry run with Test now. If the template has required inputs the defaults are filled in. The preview says which steps are skipped because they can't be simulated, or what is missing, and ends with n steps · n ms · not persisted.
You can't, and why
- Dry-run a template that declares a required input with no default value: the preview says Cannot be tested without: and names the input. None of the 17 templates does today, and a missing deploy provider or AI key does not block the test.By design
The editor
Open the editor by tapping a card, Edit in its menu, or the + button for a new workflow. From top to bottom it holds the name and description, Inputs, Workflow settings (collapsed), Permissions (its own collapsed card), the Enabled and Available to AI agent switches, Trigger, and Steps with the step tree and the + button (Add step). The top bar has close, Undo, Redo, Test now and Save. Undo keeps the last 100 states and merges consecutive edits of the same kind made within 800 ms. Closing (the x or Back) saves when the workflow can be saved; if it has content that can't be saved yet it asks Discard changes? (Keep editing or Discard); with nothing written it just closes. Save is disabled while there is an error: an empty name, no steps, an empty required parameter or an invalid input.

Name, switches and AI exposure
Name and Description sit at the top. Enabled (when off, the workflow stays saved but doesn't run) and Available to AI agent (when on, the chat agent can invoke it as a tool) come after the settings, with Description shown to the AI: if you leave it empty the workflow description is used.
You can
- Switch Enabled: it is the same switch as on the card.
- Switch Available to AI agent and write Description shown to the AI. Saving with the switch on and irreversible steps in the workflow asks Let the AI run this workflow? once (Allow the AI).
- Read the Security warning when a shell step contains a
{{…}}binding in a workflow that is exposed to the AI: the chat agent could inject text into the command through the inputs.
You can't, and why
- Have the agent call a workflow that is switched off: a workflow is announced to the chat only when it is both Available to AI agent and Enabled.By design

Inputs
Values the workflow asks for when it runs. You read them anywhere as {{var.<name>}}.
You can
- Add input with a Name (letters, digits and
_, not starting with a digit, unique), a Type (Text, Long text, Number, Yes / no, Choice, JSON), Required, a Default value, Options (comma-separated, for Choice), a Label and a Description (shown when it asks, and to the AI). Move inputs up or down, or remove them. - Run it with Run now: a workflow with required inputs opens the Run dialog with the defaults filled in, so you only change what you need.
You can't, and why
- Save with an invalid input: a blank, invalid or duplicate name, a Choice without options, or a default that is not one of the options or not a number blocks Save.By design
- Start by itself a workflow whose required input has no default: a scheduled run, an event, a shortcut or a tile has nobody to ask. The editor warns with Required with no default and the scheduler records a failed run.By design
Workflow settings
A collapsible card (Show / Hide) with settings for the whole run.
You can
- Cap for the whole run (seconds): empty is no cap. When it runs out the run is cancelled as if you had stopped it.
- When a step fails: Stop or Continue. It is the default every step inherits. A step that says Continue keeps its own choice; but with the workflow on Continue, no step can ask for Stop again.
- When a run is already going: Skip the new one (the default), Queue it (up to 10 waiting per workflow) or Cancel the one in flight. It applies to event triggers and scheduled runs; manual runs and runs started by the AI are not limited by it.
- History kept: Runs kept and Days kept. Empty means the default (100 runs, 30 days); you can set 1 to 1000 runs and 1 to 365 days. Older runs are trimmed with the workflow's next run, not when you save.
You can't, and why
- Keep a log of the events thrown away by Skip the new one: with the default policy, an event that arrives while the workflow is running is dropped without an entry in the history, on purpose: a burst of saves would otherwise write one row per event. (A run turned away by the queue or by the app-wide limit is recorded as cancelled, with the reason.)By design
Permissions
Its own collapsible card under Workflow settings, so the one decision that can make a step stop running is never hidden inside a drop-down. The summary sentence is visible even when the card is collapsed. Everything is allowed by default.
You can
- Switch Go out to the network (HTTP requests, AI steps, deploys and git push or pull), Write files (writing, checking out and backups; reading is never affected) and Run terminal commands (also the command of a database backup step).
- Add Domains it may reach: empty means any domain,
github.comalso coversapi.github.com, and what you paste is cleaned (scheme, path and port are removed). - Rely on one rule for subflows: a subflow runs with the intersection of its own permissions and its parent's, and if the domain lists have nothing in common the network is closed.
You can't, and why
- Use permissions as a security boundary: the summary ends with “This is not a sandbox: anyone who can edit the workflow can change these permissions.” They protect you from carelessness, not from a hostile author.By design
- Make the domain list restrict an AI, deploy or git step: the list only covers HTTP request steps, and the summary says so.By design
- Get protection against SSRF from the domain list: the host name is compared, not the address it resolves to, and an HTTP step can reach
127.0.0.1or10.x.By design

Triggers
A workflow has one MAIN trigger and up to six in total (Add trigger, Make it the main one). When two of them match the same event, one run starts and the main one wins. Pick the type in the dropdown: there are 25. Many carry data you read as {{trigger.<field>}}; the fields are listed in the tables.
You can
- Choose any of the 25 types, add up to 6 triggers, and promote one to the main one.
- Build a typed filter (below) so the workflow only starts for the events you care about.
- Press Capture under Capture the next event: the editor listens for 60 seconds, shows the real data of the next event of that type, and keeps it as sample data for Insert data.
- Filter On git push by branch (for example
main): the four places that emit a push (Projects, twice, the editor's Git panel and the AI chat) send the branch that was checked out, so Auto-Deploy on Push to main and Tests after Push to main fire.
You can't, and why
- Use Project closed and The AI finished its turn: they are in the dropdown but nothing in the app emits them, so a workflow that starts from them never fires. The linter warns (“Nothing in the app emits PROJECT_CLOSED yet, so this workflow will not fire.”) and Capture says “Nothing in the app emits this trigger yet, so waiting longer will not help.”Not yet
- Start from a commit made in the Source Control panel of the editor or by the AI chat: On git commit only fires for a commit made from Projects.Not yet
- Filter the four system triggers (Home screen shortcut, Quick settings tile, Text shared to PocketCode, File shared to PocketCode): Android launches them and the launcher only chooses workflows by type, so a filter is ignored.Not yet
- Read a real exit code from Command finished when the command was typed in the interactive terminal: that event comes with
exitCodeKnownset to false.Not yet - Add a seventh trigger or a ninth condition (6 triggers is as many as fit. and 8 conditions is as many as fit.).By design

.js) with Turn it into a condition.
The 25 triggers
Git (2)
| On git push | After a push from Projects, the editor's Git panel or the AI chat. Fields: projectId, projectName, branch (the branch that was pushed, for example main). |
| On git commit | After a commit made from Projects. Fields: projectId, projectName, message, branch. |
Files (4)
| On file save | Fields: filePath, language, linesChanged. |
| File created | Fields: filePath, fileName. |
| File deleted | Fields: filePath, fileName. |
| File renamed | Fields: filePath, previousPath. |
Projects and builds (5)
| Project opened | When you select a project. Fields: projectId, projectName. |
| Project closed | Listed, but nothing emits it: it never fires. |
| Build finished | Fields: status, exitCode, durationMs, output. |
| Run finished | Fields: filePath, runtime, exitCode, output. |
| Command finished | Fields: command, exitCode, output, exitCodeKnown. |
Deploys, data and tools (5)
| Deploy completed | Fields: provider, projectName, status, url. |
| Deploy failed | Fields: provider, projectName, error. |
| Query executed | Fields: data, format, rowCount, columns. |
| API tester response | Fields: url, method, status, durationMs. |
| Design exported | Fields: designId, designName, format. |
Errors and the AI (3)
| An error was detected | Hears the failure of another workflow, build and run errors of the editor, and terminal commands run by the AI that exit with a code other than 0. A workflow never triggers itself. Fields: source, message, filePath, exitCode, workflowId, workflowName, error. |
| The AI changed a file | A file written by the AI agent. It is separate from On file save on purpose: an automatic write must not fire the automations you built for your own work. Fields: filePath, fileName. |
| The AI finished its turn | Listed, but nothing emits it: it never fires. |
The app and manual (2)
| App opened | When the app comes to the foreground. Field: sessionId. |
| Manual or scheduled | No data. It is what you start with ▶ or Run now, what a schedule starts, and what the AI chat runs. |
From Android (4)
| Home screen shortcut | No data. See Running and watching. |
| Quick settings tile | No data. |
| Text shared to PocketCode | Fields: text, subject. |
| File shared to PocketCode | Fields: uri, fileName, mimeType. |
The typed filter
Under a trigger, Add condition (up to 8) gives a Field (the fields of that trigger), a Comparison and a Value. Join them with All or Any, and put Not on any of them. With no condition the editor says “No condition: this trigger fires with every event of its type.” Changing the type drops the conditions whose field doesn't exist in the new type and tells you. A workflow saved with the old free-text filter keeps it as Text filter, still working, with Turn it into a condition.
| Comparison | What it does |
|---|---|
| is | The field equals the value. |
| contains | The field contains the value. |
| starts with / ends with | The field starts or ends with the value. |
| matches path | A glob for path fields: one * stays inside a folder, two cross folders, and a leading dot matches the extension. |
| is one of | The field is one of several values separated by commas. |
| is empty | The field has no value. |
| is greater than / is less than | Numeric comparison. If either side is not a number the condition does not match. |
Steps: the tree, the card and the palette
The Steps list is a tree: blocks nest inside blocks. Steps are numbered 2, 2.1; an else branch reads 2.e1, a catch branch 2.c1 and a parallel branch 2.<n>. Blocks can be collapsed (Collapse / Expand), and a step nested very deep gets a notice such as 5 levels deep saying it still runs the same but stops fitting on a phone screen.
You can
- Tap the + button (Add step) to open the palette: search by name, description or output (“Name, description or output (stdout, url…)”), pick a category chip (Shell, Git, Deploy, AI, Data, HTTP, Files, Control, Notify, Other), and use favourites and the last 5 recents. Each entry shows what it gives (Gives: …) and marks irreversible, runs commands, network, writes files or Cannot be simulated. The new step lands at the end of the slot you chose and its settings open.
- On each card: the reorder handle, the number, the title and a one-line summary, an On / Off switch (an Off step is skipped and does not count as a failure), the If this step fails chip, Test this step, the pencil (opens the settings and selects the step) and the ⋮ menu.
- In the menu: Move up, Move down, Copy step, Paste below (only active when the clipboard holds PocketCode steps, so you can paste into another workflow), Duplicate, Note (it only shows in the editor), Turn into a subflow and Delete.
- Spot pinned data: the card of a step with a pinned output shows sample data.
You can't, and why
- Drag a step into another block: the handle moves a step one position for every 48 dp of drag inside its own list; use Move up and Move down from the menu.By design
- Draw the flow as a graph, or use an N-way switch or a free merge: the flow is a nested tree, If / Else has exactly two branches and In parallel joins its branches with one of three policies.By design
- Edit a step the app doesn't know (Unknown step, written by a newer version): it is kept as it is and can only be moved or deleted.By design


2.1 and 2.2 under If it matches, 2.e1 under Otherwise. Deploy offers Run this step for real because it cannot be simulated.The seven kinds of step
| Kind | What it does | What you set |
|---|---|---|
| Action | Runs one of the 15 actions. | The action's parameters. Only on an action: Reliability (retry, timeout) and Conditional (When). |
| If / Else | Runs If it matches when the condition is true and Otherwise when it is not. | A condition tree with AND, OR and NOT. |
| Loop | Repeats its steps For each item of a list. | List to go through, Name for each item (read it as {{item.<name>}}), Most iterations (default 100, never more than 10 000) and Iterations at once (1 runs them one after another, up to 16). |
| In parallel | Runs several branches at the same time. | Branches (add one, or remove one that is empty) and When do we move on: When they all finish, With the first one to finish or With the first one that works. The last two cancel the branches that lose, mid-way and with their side effects. |
| Try / on failure | Runs Try this; if anything in it fails, runs If it fails. | Name for the error (default error, read as {{var.error}}, up to 4 096 characters). |
| Subflow | Runs another workflow with the values you give it and uses its last result. | Workflow to run and Values for the subflow. Up to 5 levels deep, no recursion, and permissions are the intersection with the parent's. |
| Wait | Pauses the workflow for a time, or until something happens. | A time in milliseconds, or Wait for something to happen with Event to wait for, an optional filter (same rule as a trigger) and Cap in milliseconds (5 minutes if you set none). |
Actions
Fifteen actions, in eight palette categories. Each one lists the outputs you can read as {{step.<id>.output.<key>}}; the names below are the keys. The labels are the English ones the palette shows.
Shell (1)
| Run terminal command | Runs a command in the terminal's shell. Parameters: command, cwd, env, failOnNonZero (on by default), timeoutMs. Outputs: command, exitCode (-1 if the cap killed it), stdout, stderr (each limited to 64 KB, head and tail), durationMs, timedOut. |
Git (1)
| Git operation | Seven operations: status, commit, push, pull, checkout, log, diff. Parameters: operation, message, branch (letters, digits, ., _, /, -), n (default 20), path, projectPath. Outputs: sha, branch, changedFiles, ahead, behind, text. Only push (or an operation that comes from a binding) counts as irreversible; commit, pull and checkout write files; status, log and diff touch nothing. diff is per file. |
Deploy (1)
| Trigger deploy | Triggers a deploy on render, netlify, digitalocean or railway and waits for the provider's verdict (15 minutes by default, 1 to 60). Parameters: provider, project, timeoutMs; branch and env are recorded but not honoured. Outputs: status, url, provider, projectName, logsTail, durationMs, timedOut. It cannot be simulated: Test now skips it and the step test offers Run this step for real. On Free it fails with “Upgrade required to trigger another active deploy” when a deploy of that project is already in flight (queued, building or deploying), and you see a notice that the action needs PocketCode Pro. |
AI (2)
| Ask AI to analyze | Sends a prompt, with optional context, to your active AI provider. Parameters: prompt, context, outputFormat (TEXT or JSON), schema. Outputs: text, json (only in JSON mode) and tokensEst, a local estimate of the tokens, not the provider's count. |
| Ask AI to generate | The same, framed as code generation. Parameters: prompt, context, language. Outputs: text, tokensEst. It does not write files; use Write file with its text. |
Data (4)
| Query database | Runs SQL against a named connection: neon, supabase, turso, upstash or cloudflare (D1), or one of your saved PostgreSQL connections (by name or id). Parameters: connection, sql, maxRows (200 by default, 5 000 at most), allowWrites. Outputs: rows, rowCount, columns, truncated, durationMs, message, writes. A query with write verbs (DROP, DELETE, TRUNCATE, UPDATE, INSERT, ALTER, CREATE, GRANT), or SQL that comes from a binding, counts as irreversible and fails unless allowWrites is on. The palette hint calls it read-only; it is not. |
| Backup database | Runs your own backup command (for example pg_dump); with no command it can only copy PocketCode's internal database. Parameters: connection, command, outputDir, timeoutMs (10 minutes). Outputs: filePath, sizeBytes, tables, exitCode, stdout, stderr, timedOut, durationMs. |
| Set variable | Parameters: name, value. Outputs: name, value. It writes {{var.<name>}} for the steps that follow (the value can also be read as {{step.<id>.output.value}}). A dry run (Test now) does not write the variable. |
| Transform value | Evaluates an expression with the filters and returns value. No side effects, and a dry run does the same as a real run. |
HTTP (1)
| HTTP request | Parameters: method, url, headers (JSON), authorization (a secret), body, contentType, timeoutMs (1 000 to 120 000, 30 000 by default), followRedirects. Outputs: status, headers, body (up to 128 KiB), json, durationMs, bodyTruncated, finalUrl, redirects. Only http and https; up to 5 redirects, and credentials never cross to another origin. |
Files (4)
| Read file | Parameter: path. Outputs: content (up to 128 KiB), sizeBytes, exists, contentTruncated, filePath. |
| Write file | Parameters: path, content, append. Outputs: filePath, sizeBytes, bytesWritten, overwritten. It is never counted as irreversible, not even when it overwrites. |
| File exists | Parameter: path. Outputs: exists, isDirectory, sizeBytes, filePath. |
| Open file in editor | Parameters: file, line. Outputs: opened (true only if the editor confirms within 1.5 seconds, so it is false with the app in the background), file, line. |
Notify (1)
| Show notification | Parameters: title, message, deepLink (only pocketcode://workflows/…), importance (LOW, DEFAULT, HIGH). Only HIGH uses the Workflows · alerts channel; the rest go to the silent Workflows channel. Outputs: notificationId, delivered (it means the event left for the notification system, not that you saw it; false in a dry run), deepLink, importance. |
- The three file actions that read or write (Read file, Write file, File exists) are confined to the root of the project; Run terminal command and Git operation are not.
- In the palette, irreversible marks the worst case of the type; the confirmation dialog, the step test and the Problems panel look at the values you actually typed.
You can't, and why
- Deploy to any provider: only
render,netlify,digitaloceanandrailwayhave a call that triggers a deploy, and the branch and environment are not honoured.Third party - Query a saved connection that is not a remote PostgreSQL one (the embedded local database, MySQL and the rest): from a workflow you can only reach
neon,supabase,turso,upstash,cloudflare(D1) and your saved PostgreSQL connections.Third party - Back up any database without a command: with no
commandthe step can only copy PocketCode's internal database.Not yet
Conditions: If / Else and When
An If / Else step holds a condition tree and two branches. A step of kind Action can also carry When (expression), under Conditional: the step is skipped when the expression resolves to empty, false, 0 or null. When exists only on action steps.
You can
- Build the condition with Add condition and Add group, combine with AND, OR and NOT, and use Group it and Remove. An empty group always matches.
- See It matches or It does not match, evaluated with your pinned sample data, not with the next run.
You can't, and why
- Put When on a loop, a parallel, a try, a subflow, a wait or an If / Else: only an action step has it.By design
| Operator | True when |
|---|---|
| equals / is not | The two values are equal, or not. |
| greater than / less than | Numeric comparison. |
| greater or equal / less or equal | Numeric comparison, inclusive. |
| contains / starts with / ends with | Text comparison. |
| matches | A regular expression (keep it short). |
| is one of | The value is one of several separated by commas. |
| is null / is empty / is true | Checks the value itself. |
| always | Always true. |
Variables and expressions
Any parameter takes a literal or an expression between double braces: {{ root.field[0] | filter:"arg" | filter }}. Insert data opens a picker (Inputs, Trigger, Earlier steps, Step status, and the item or the error of the block you are in), so you never type a step id by hand; it warns Inside a branch: it may not have run and “Inside a loop: only the last iteration is left”. A reference that doesn't resolve gives an empty string. \{{ writes a literal {{. Filter arguments always go in double quotes: replace:a:b is a syntax error, replace:"a":"b" works.
You can
- Chain filters with
|after any reference. - Pin an output as sample data, so Insert data and If / Else can preview with it.
You can't, and why
- Add your own functions or run code in an expression: the list of 13 filters is closed, with no user functions and no
eval; very long paths, filter chains or text between braces are rejected when parsed.By design
| Expression | Resolves to |
|---|---|
{{var.<name>}} | A declared input (including the values of Run with these inputs and the defaults of a schedule or shortcut), the error name of a Try / on failure, the values a Subflow passes to its child, and the value a Set variable step writes (a dry run does not write it). |
{{step.<id>.status}} | SUCCESS, FAILURE, SKIPPED, TIMED_OUT, or RUNNING for a step still going. |
{{step.<id>.output}} | The output map of the step, or one field of it: {{step.<id>.output.json.items[0].name}} walks into JSON with [n]. |
{{step.<id>.error}} | The error message of a step that failed. |
{{item.<alias>}} | The current item of a Loop (the bare alias works too). |
{{trigger.<field>}} | The data of the event that started the run; {{trigger.type}} tells which of the workflow's triggers it was (MANUAL when there was no event). |
{{secret.<NAME>}} | A saved secret. It is terminal: you can't walk inside it. |
The 13 filters
| Filter | What it does |
|---|---|
lines | Splits text into lines; one trailing newline is dropped. |
first / last | The first or last item of a list, or the first or last character of text. It fails on empty. |
trim / upper / lower | Trims spaces, upper-cases, lower-cases. |
length | The number of items of a list or characters of text. |
json | Renders the value as JSON. |
default:"x" | A fallback when the value is missing or empty. |
split:"," | Splits text on a separator into a list. |
join:"," | Joins a list with a separator. |
date:"HH:mm" | Formats a date from epoch milliseconds or an ISO date, in the device's time zone. |
replace:"a":"b" | Replaces text; the text to replace can't be empty. |
Examples
{{step.<id>.output.stdout | lines | first | trim}} | The first line of a command's output, trimmed. |
{{step.<id>.output.json.items[0].name | default:"none"}} | A field inside a JSON response, with a fallback. |
{{trigger.filePath | replace:"src/":""}} | The saved file's path without a prefix. |
Loops, parallel, try / on failure and subflows
The blocks of the tree, with the limits that matter in practice.
You can
- Loop: up to 10 000 iterations (default 100) and up to 16 at once; with Iterations at once above 1 they run in batches.
- In parallel: When they all finish waits for every branch and fails if one fails; With the first one to finish and With the first one that works cancel the others.
- Try / on failure: the failure branch reads the message in
{{var.<name>}}; the failure still shows in the history. - Subflow: build the part once and call it from several workflows; Turn into a subflow extracts a step and everything inside it into a new workflow that is switched off, and leaves a subflow step in its place, listing the references that will break (They will resolve to nothing, quietly.).
You can't, and why
- Nest subflows more than 5 levels or let a workflow call itself: a recursive subflow is skipped and the linter warns.By design
- Loop more than 10 000 times or run more than 16 iterations at once, whatever the field says.By design
Retry, timeout and failure
Open the settings of an action step and expand Reliability. These fields exist on action steps only.
You can
- Set Max attempts (1 means no retry), Wait between retries (a text field:
EXPONENTIAL,LINEARorFIXED), Initial delay (ms), Max delay (ms) and Timeout (ms) (empty means no cap). - Rely on timeouts being retried: a step that times out is marked
TIMED_OUTand, if attempts remain, it runs again like any other failure. - Choose If this step fails: Stop (the run ends here), Continue (it goes on and the failure stays in the history) or Use the workflow setting. With Continue the step stays red and the run can still end green.
- Read the result in the run detail: succeeded on attempt n, or n attempts if it never did.
You can't, and why
- Set a retry or a timeout on a loop, a parallel or any other control block: the fields exist on action steps only. The workflow-wide cap is in Workflow settings.By design
Test a step, pin data, test the workflow
You can try things without running the whole workflow.
You can
- Tap Test this step: it simulates the step with your pinned data as context and says Simulated in n ms: nothing was touched. It warns No pinned output for: … when a reference points at a step with nothing pinned.
- When the action can't be simulated (today only Trigger deploy), or the values you typed would be irreversible, the button is Run this step for real. It asks first: only that step runs, the rest of the workflow is untouched and the run is not saved to history.
- Pin a step's output (and Unpin it) as sample data for the picker and the previews. Pinned outputs live on the device, up to 50 steps per workflow, and are dropped after 14 days.
- Tap Test now (or press
Ctrl+Enter) to dry-run the whole workflow as it is on the screen, not as it was last saved. It shows Test passed or Test failed and n steps · n ms · not persisted. A dry run saves no run and fires no events.
You can't, and why
- Test a control-flow block on its own: “Only action steps can be tested on their own: testing a branch or a loop means running what is inside it.”By design
- Use secrets in a dry run: they are not resolved, and the step is skipped telling you which ones it uses.By design
- Export or sync pinned outputs: they stay on the device.By design
Problems
The linter runs while you edit and lists Errors, Warnings and Tips with a count for each. Every row names the rule, the step (Step: … or Whole workflow) and has Go to step. When there is nothing it says Nothing to fix. The same linter checks what the AI generates and what you import.
You can
- Fix what a warning points at, or leave it: only the three rules that are errors block Save.
- Jump straight to the step with Go to step.
You can't, and why
- Save with an error (an empty name, no steps, a required parameter left empty): the three error rules are the ones that would leave the workflow unreadable or unsaveable. Everything else, permission rules included, warns and does not block, because someone who closes the network usually does it before removing the step that used it.By design

The 34 rules
| Group | Rules |
|---|---|
| Structure (6) | Error: the workflow has no name; it has no steps. Warning: an empty branch; a step that can never run. Tip: a parallel with one branch; nesting too deep. |
| Parameters (3) | Error: a required parameter is empty. Warning: a parameter the action doesn't have; an action type no installed host serves. |
| References (7) | All warnings: a reference that will never resolve; one that reads a step that runs later; an output the step doesn't return; a trigger field the trigger doesn't carry; an undeclared variable; a reference to a switched-off step; a reference that goes into a shell command unquoted. |
| Triggers (3) | Warning: a trigger nothing emits; a filter on a field the trigger doesn't carry. Tip: the same trigger twice with the same filter. |
| Loops (3) | All warnings: no list to go through; an alias already taken; no alias. |
| Reliability (2) | Warnings: an absurd timeout; an absurd retry. |
| Security (2) | Warnings: a secret typed in plain text; an irreversible step in a workflow that only runs on its own. |
| Permissions (4) | Warnings: a step that goes to the network, writes files or runs a command while that permission is off; a step that goes to a domain not in the list. |
| Coherence (4) | Warnings: exposed to the AI with no description; a required input with no default on an event trigger; a recursive subflow; a subflow that points to nothing. |
Running and watching
Every run is written to the history when it ends: each step's result, how long it took, how many attempts it needed and its error. How much is kept is set per workflow in Workflow settings: 1 to 1 000 runs and 1 to 365 days (the defaults are 100 runs and 30 days). Anything that starts a run can also stop it.
Starting and stopping a run
A run starts from a trigger, from ▶ or Run now, from a schedule, from the AI chat, or from a shortcut, the tile or the Share menu. Across all workflows the app runs up to 8 runs at a time and keeps up to 16 waiting for up to 120 seconds; beyond that the run is recorded as cancelled with the reason “the app was already running too many workflows at once”.
You can
- Tap ▶ on the card of a workflow whose main trigger is Manual or scheduled, or Run now in the menu of any workflow. If it declares required inputs, the Run dialog opens first (“This workflow needs these values before it can run.”) with the defaults filled in.
- Stop it from the card, the menu, the history, Activity, the run detail or the notification. The run ends as Cancelled.
- Switch on a workflow that has irreversible steps: a dialog titled “This workflow does something irreversible” lists them (Step n · …) and you choose Enable anyway. It is asked once per workflow and remembered on the device, not synced and not exported.
- Save a workflow with Available to AI agent on and irreversible steps: Let the AI run this workflow? (Allow the AI), also once. Without that permission the agent's tool refuses to run it and tells the model who to ask.
You can't, and why
- Be asked about irreversible steps when you press Activate on a template, use Save & enable in the generator, or import a file (an import arrives switched off, and the question comes when you switch it on).Not yet
- Be warned about overwriting a file: Write file is never counted as irreversible, not even when it overwrites; its
overwrittenoutput tells you afterwards. Only a Gitpush(or a Git operation that comes from a binding) and SQL with write verbs (or SQL that comes from a binding) count.By design
Activity tab
The latest runs of every workflow, live ones first, 50 at a time.
You can
- Search in the errors: it looks in the run's message and in the message of every step.
- Filter by status (Completed, Failed, Cancelled), by date (Any date, Today, Last 7 days, Last 30 days) and by workflow (Every workflow, including workflows you have already deleted); Clear removes the filters.
- Load more adds 50 more, stop a live run, and tap a run to open its detail.
- Copy the filtered runs as JSON with Export as JSON: it puts the text on the clipboard.
- Delete history after a confirmation (“The runs disappear. The workflows stay as they are.”), for every workflow or only for the filtered one.
You can't, and why
- Go back further than the 500 most recent runs: “That is as far back as this screen goes. Narrow the filter to find something older.”By design
- Export the history to a file: Export as JSON only copies the text.Not yet
Run history of one workflow
Run history on a card lists that workflow's runs, newest first.
You can
- See each run's status and time, its number of steps, Triggered by … and, for a cancelled one, Cancelled by …; a run still going carries In flight.
- Stop this run, or open a run for its detail.
- With nothing yet it says “No runs yet — trigger this workflow to start a history.”
You can't, and why
- Read every cancellation reason in words: the app translates the previous run was still going, the queue was full and “the app was already running too many workflows at once”; the other reasons (
user,timeout,superseded,scope) are shown as the raw word.Not yet
Run detail
Open a run from the history, Activity, a run notification or a deep link.
You can
- Read the header (status, duration, trigger, who cut it) and every step: result, duration, succeeded on attempt n or n attempts, the error and the output as a JSON tree you can expand and copy. A step that was still running when the run ended says Interrupted; a step removed from the workflow since says This step is no longer in the workflow.
- Follow Live output of the shell while the run is going, search it (Search the log) and copy it (Copy the log). Only the last 500 lines of each step are kept, and the screen says so when older lines were dropped.
- Analyse the whole run with AI, or Analyse with AI on one step: it opens the chat with a prompt already written.
- Copy as JSON copies the run.
You can't, and why
- Read the shell log of a run that has finished: “The shell log is not kept in the history: it is only visible while the run is going.”By design
- Find a run that was in flight when the system killed the app: a run is written once, when it ends, and nothing is recovered at start-up, so an interrupted run leaves no row.By design
- See a stored secret: values are masked as
•••when the run is written, so they are not in the database either. Values shorter than 4 characters can't be masked.By design
Run again, repeat from the failed step, run with inputs
Three buttons at the bottom of the detail, all ending in the Repeat this run dialog.
You can
- Run again runs the workflow from the start.
- Repeat from the failed step runs again from the first step that failed, reusing the results of the steps before it (n earlier results are reused.). It shows only when the run ended and has a failed step.
- Run with these inputs asks for the inputs again before it runs.
- Read the dialog before you confirm: it says “It runs the workflow as it is now, not as it was when this run happened.”, whether the workflow was edited since, which steps no longer exist, which were added and where it resumes.
You can't, and why
- Reuse the inputs of the old run: “The inputs of that run are not saved, so the declared defaults are used.” They could be tokens.By design
- Resume from a step nested inside a block: only a first-level step can be the restart point.By design
- Repeat a run whose workflow you deleted: “The workflow no longer exists: this run cannot be repeated.”By design
Run notifications
A run that is alive shows a persistent notification with Step n of m and a Stop button. While runs are going PocketCode keeps a foreground service of the special use type, so Android does not stop the app halfway.
You can
- Follow a run from the notification shade and stop it from there; the stop button only reaches live runs of this app.
- Send your own notification with a Show notification step. Its importance decides the channel:
HIGHgoes to Workflows · alerts, anything else to the silent Workflows channel. Both follow the app's notification settings: the global switch, the alerts and notices switches, Android's notification permission and quiet hours. - Tap a notification: a link to
pocketcode://workflows/…opens the run or the workflow; any other link is dropped and the notification just opens the app.
You can't, and why
- Get an automatic notification when a run fails: PocketCode sends none. If you want one, add a Show notification step in a Try / on failure branch, or build a workflow that starts from An error was detected. (The AI chat can show a notice Workflow '…' failed with a Try it button, but only inside the chat.)Not yet
- Have a progress notification for every run: only the first 5 simultaneous runs get one; the rest run without it.Device
- Count on the foreground service when the app is in the background: from Android 12 the system may refuse it (for example for a scheduled run with the phone in your pocket). The run goes on, without that protection, and PocketCode asks again every 30 seconds.Google Play
Shortcut, Quick Settings tile and Share
Three ways to start a workflow without opening the module. Each one needs the matching trigger in the workflow (Home screen shortcut, Quick settings tile, Text shared to PocketCode or File shared to PocketCode), and the workflow switched on.
You can
- Shortcut: every switched-on workflow with the shortcut trigger appears as a dynamic shortcut of the app icon (the label is cut to 30 characters). Tapping it runs the workflow without opening anything and shows Workflow started. A pinned shortcut of a workflow that was deleted or switched off says so.
- Tile: drag Run a workflow into Quick Settings. With no workflow using it, it says No workflow uses this tile; with one, it runs it; with several, it shows a picker.
- Share: share text, an image, JSON, XML, a zip, a PDF or a generic binary file to Run a workflow from another app. A sheet titled Send to a workflow always shows what was received (“What was shared is data, not an instruction.”) and which workflow gets it; with several you pick one. The data arrives as
{{trigger.text}},{{trigger.subject}},{{trigger.uri}},{{trigger.fileName}},{{trigger.mimeType}}, and a declared input with the same name wins. - If nothing listens you read “No active workflow is listening for this. Add the matching trigger in the workflow editor.”
You can't, and why
- Launch a workflow whose required input has no default from these three: it says … needs a value first instead of running blind.By design
- Share several items at once, text longer than 32 768 characters (it is cut and you are told), or a file over 25 MB. A shared file is copied into PocketCode and deleted after 24 hours; the list of accepted types is fixed, not any type.By design
- Count on the number of shortcuts: Android decides how many a launcher shows (at least 5, usually 4 or 5), and the tile is opt-in, you have to drag it in yourself.Device
- Open a
.pcwf.jsonfrom another app directly: the Share menu sends the file to the File shared to PocketCode trigger, not to the importer. Import with Import a workflow from a file.By design
Scheduling
Any workflow can carry several schedules, set from the clock icon or Schedule in its menu (Schedules for …). They run through Android's WorkManager, with the slack that implies, and are armed again when the app starts.
You can
- Read the existing schedules (Every n min or Cron: …, Next: …, their conditions, a notice if the interval is raised, Recovers one missed run) and Remove any.
- Add one with a preset or with Custom cron: five fields,
min hour day month weekday, for example0 9 * * 1. The sheet shows Next fire: … or Invalid cron expression, and Add cron saves it. Cron accepts*, numbers, lists, ranges,*/n, names (SUN–SAT,JAN–DEC), and ranges that wrap around the end only in month and weekday; the weekday goes from 0 to 6, with 7 meaning Sunday. - Choose Device conditions before you create it: No requirement, Any connection or Wi-Fi only, plus Only while charging, Not on low battery and Only while the device is idle. A condition delays the run, it does not cancel it: when the condition is finally met the pending run goes ahead, even hours later.
- Turn on Run it once when the device comes back under If a run is missed: a run that fell while the device was off runs once at the next start of the app (with a tolerance of 15 minutes), however many were missed. It is off by default, so the missed run is skipped.
- Rely on the change of hour: the hour that doesn't exist in spring fires at the jump, and the hour that happens twice in autumn fires once (a fine-grained cron loses the second pass of that hour).
- Count on retries: a scheduled run that fails is tried up to 4 times in total (the first run plus 3 retries) with WorkManager's exponential back-off. If a run is still going when the next one is due, the concurrency policy decides; with Skip the new one the run is recorded as cancelled, the previous run was still going.
- Read the banner Scheduled workflows need attention above the tabs: it appears when PocketCode's notifications are off, when the Workflows · alerts channel is blocked, or when the app is subject to battery optimisation (“Android may delay scheduled runs. It does not cancel them, they go out later.”). It has Open settings and no dismiss button; it goes away when the cause does.
You can't, and why
- Get a guarantee under 15 minutes: Android does not run scheduled work more often than every 15 minutes. An interval below that is raised to 15 and the sheet says so (“Asks for every n min, but it runs every 15 min: that is the floor Android allows.”); a cron below it gets “Android does not guarantee that rate in the background”. PocketCode asks for neither the exact-alarm permission nor an exemption from battery optimisation.Google Play
- Type an interval of your own: only three intervals are offered as presets (every 15 minutes, every hour, every 6 hours); any other rhythm is a cron expression. An interval can't be longer than about 30 days.By design
- Choose a time zone: there is no selector, and a new schedule reads its cron in the device's zone (each schedule stores a zone, but the screen doesn't expose it).Not yet
- Edit a schedule or its conditions: remove it and add another.By design
- Use
?,L,#, a step over a range (1-9/2) or a year field in a cron expression. A cron that never fires (for example the 31st of February) switches the schedule off.By design - Be told by the banner about manufacturer battery killers: it only says what Android answers (notifications off, channel blocked, battery optimisation).Device
The presets
| Preset | What it adds |
|---|---|
| Every 15 minutes | An interval of 15 minutes, the Android floor. |
| Every hour | An interval of 60 minutes. |
| Every 6 hours | An interval of 6 hours. |
| Daily at 9:00 | The cron 0 9 * * *. |
| Mondays at 9:00 | The cron 0 9 * * 1. |
Secrets
Manage secrets (the key icon of the list) is a list of names with no values. You reference one as {{secret.NAME}} in any parameter, so a token never has to be typed into a workflow, where it would be saved as is, travel when you export it and show up in the run history.
You can
- Add a secret: a Name in capital letters, digits and underscore (if the name can't be used in an expression the screen suggests one, Use …), and a Value. It is the name the steps use, so changing it later breaks them.
- Change value: workflows that use it pick up the new value on their next run.
- Delete: a dialog lists the workflows that reference it and warns that the value can't be recovered and that a workflow that loses its secret doesn't fail when saved, it fails on its next run sending an empty value.
- Read “Stored encrypted on this device, one set per account. Values are never shown again, not even here.”
You can't, and why
- See a value again after you save it, or save an empty one (“An empty value is not saved. To remove a secret, delete it.”).By design
- Have a value masked in the run history when it is shorter than 4 characters: it is saved, but the screen warns “Careful: this value is shorter than 4 characters, so it will NOT be masked” and a step that prints it leaves it readable there.By design
- Open the store after you restore the phone or change the screen lock: “The encrypted store could not be opened on this device… Nothing has been deleted. This usually happens after restoring the phone or changing the screen lock.”Device
- Sync secrets between devices: they are removed from what is uploaded, and they don't travel in an exported file either.By design
Export, import and links
A workflow travels as a .pcwf.json file. Exporting and importing are free on purpose, and the code says why: they are the only way to take your work out of the app, and a way of getting your data out locked behind a subscription would turn a plan into a lock.
You can
- Share as file (in a card's menu) opens Share this workflow: the file name, which secret fields are emptied (Your secrets stay on this device), and the reminder that run history, pinned outputs and the on/off switch don't travel. Share opens Android's app picker.
- Import a workflow from a file (the top button of the list) opens the system file picker. The Import workflow sheet shows the name, Runs when, up to 40 steps, You will have to fill these in for the secrets, and the linter result; Save is blocked if there is an error. “It will be saved switched off. Read it before you turn it on: a workflow can run commands on your device.”
- Open a link
pocketcode://workflows/import?url=https://…from another app: A link wants to import a workflow shows the address (From: …) and a warning, and nothing is downloaded until you press Download (or No thanks).
You can't, and why
- Open a
.pcwf.jsonfrom a file manager or another app directly: the app has no file filter for it. Use Import a workflow from a file or the link.By design - Import a file bigger than 512 KB, a file that isn't a PocketCode workflow, a damaged one, or one written by a newer version of PocketCode: each gets its own message.By design
- Use a link that isn't
https, is longer than 2 048 characters, has credentials in the address or points at the device itself; a redirect is shown and not followed.By design - Share a file without checking it: only parameters declared as secrets are emptied; HTTP headers and commands travel exactly as you typed them, so check the file before you share it if a field holds a key or a token.By design
What is in the file
| Leaves | The name, description, triggers, steps, inputs and the run settings (permissions and tags included). |
| Does not leave | The id, the dates, the last run's state, the template it came from, the on/off switch, Available to AI agent, pinned outputs, the history and the schedules. |
| Secrets | Parameters declared as secrets are emptied and listed. A {{secret.NAME}} reference does travel: it is a name, not the secret. |
| Arrives | Switched off and with a new id, after the linter has run. A new action from a newer build is dropped alone; a file with a newer format is rejected whole. |
AI: generate, change and the chat
The AI touches workflows in three places: the generator and the change sheet in this module (free), the chat agent that can read, run and, with Pro, write them, and the Analyse with AI buttons of a run.
Generate from prompt and Change with AI
Both live in the module and neither has a plan check. The model is the AI provider you configured in Settings, with your own key.
You can
- Tap Generate from prompt on the welcome screen (portrait) to open Generate workflow from prompt: write the Prompt, mentioning the trigger (push, save, commit, error, deploy) and the actions (deploy, notify, backup, test, format), and press Generate.
- Tap Change with AI in a card's menu to open Change “…” with AI: say what you want changed; the rest of the workflow stays as it is and you see what changed before saving.
- Review the result: the preview, Checks (linter problems), Dry run passed in n ms, Dry run failed: … or “Not tested: … You can test it yourself from the editor.”, Adjusted automatically for what the app repaired, and, when changing, the diff (added, removed, changed, n steps unchanged).
- Choose Save & enable (only when creating), Open in editor (the way out when the checks block saving) or Discard. A workflow created this way is saved switched on; a change keeps the workflow's id, its on/off state and its creation date.
You can't, and why
- Count on a dry run for everything the AI makes: it only runs when the app judges it safe, because a dry run executes steps. When a step can't be simulated, the waits add up to more than 10 seconds, a wait is for an event or a subflow can't be inspected, it says Not tested and gives the reason.By design
- Get a workflow written by a model without an AI provider: with no key set the app falls back to keyword matching and says “Built without a model: no AI key is set, so this came from keyword matching.”Needs network
- Save a generated workflow that the linter rejects: “Fix these before saving: this workflow is not ready.”By design
The chat agent and workflows
Two different things. A workflow you mark Available to AI agent and keep switched on is announced to the chat as its own tool, workflow__<name>__<last 6 characters of the id>, with a description built from its steps (it warns about irreversible ones) and an input schema built from its declared inputs. And six management tools are always there, with or without exposed workflows.
| Tool | What it does | Plan |
|---|---|---|
workflow__list | Lists your workflows (up to 25) with triggers, whether they are enabled and how the last run went; it can filter. | Free |
workflow__get | Returns one workflow in full. Secret parameters appear as [secret, not shown]. A workflow longer than 20 000 characters is refused, not cut. | Free |
workflow__runs | The history of one workflow, newest first (5 by default, up to 20), with the last error and up to 5 failed steps. | Free |
workflow__run | Runs a workflow now. It refuses one that is switched off, validates the inputs and respects the irreversible-steps permission. | Free |
workflow__create | Creates a workflow from a document. It is validated first, and it is born switched off even if the model asks for it on. | Pro |
workflow__update | Changes fields of an existing workflow. | Pro |
You can
- Ask the agent which workflows run when you push, or why last night's backup failed: it reads with
workflow__list,workflow__getandworkflow__runs, which are free. - Ask it to run one with
workflow__run: it validates the inputs against the ones the workflow declares, and respects the irreversible-steps permission you gave (Allow the AI). - With Pro, ask it to create or change one:
workflow__createandworkflow__update. The three tools that write go through the agent's confirmation sheet.
You can't, and why
- Create or change workflows from the chat on Free: the model gets a refusal that says to tell you, and you see a notice (“… needs PocketCode Pro, so that action did not run.”) with an Upgrade button. The plan feature is called Workflows from the chat.Pro
- Let the agent change a workflow's retry, timeouts, When condition or retention: the AI can't set them, and an update keeps the ids of the steps, the permissions, the tags and the retention.By design
- Use Available to AI agent as an access control: it only decides whether a workflow is announced as its own tool.
workflow__runcan run any workflow that is switched on, by name.By design
Marketplace
The Marketplace has a Workflows asset type, but today a workflow can't be installed from it, and the app has no way to publish one. To share a workflow, use a file or a link (see Export, import and links).
You can
- Filter the Marketplace by the Workflows kind and read the page of an asset of that kind.
- Share your own with Share as file, or host a
.pcwf.jsonon an https address and send apocketcode://workflows/import?url=…link.
You can't, and why
- Install a workflow from the Marketplace: on the page of a workflow asset the install button is disabled (Requires WASM runtime), the same as for a plugin, even though the engine already knows how to check and install one.Not yet
- Publish a workflow to the Marketplace: there is no button and the app can't upload anything. The catalogue is published by the team through a pull request that CI validates and signs.By design
Free and Pro
The engine is free. What costs money is narrow, and each item is a limit you can reach from outside this module. Prices are in Plans & pricing.
| Feature | Free | Pro |
|---|---|---|
| 25 triggers, 15 actions, seven kinds of step, templates, the editor, the linter and step tests | Yes | Yes |
| Scheduling (WorkManager, cron, device conditions, missed-run recovery) | Yes | Yes |
Encrypted secrets, per-workflow permissions, history and Activity, export and import of .pcwf.json | Yes | Yes |
Available to AI agent, and the chat running your workflows (workflow__run, workflow__list, workflow__get, workflow__runs) | Yes | Yes |
| Generate from prompt and Change with AI in this module | Yes, with your own AI provider | Yes, with your own AI provider |
The AI chat creating or changing workflows (workflow__create, workflow__update) | No: the model gets a refusal and you see a notice with Upgrade | Yes (Workflows from the chat) |
| The Trigger deploy step while a deploy of the same project is in flight (queued, building or deploying) | No: 1 in flight per project (“Upgrade required to trigger another active deploy”) | Yes, no cap |
| Sync of workflow definitions between your devices (Cloud Sync, the Workflows group) | No | Yes |
Keyboard shortcuts
These work only while the editor is open and on a hardware keyboard. They can be changed in Settings.
| Key | What it does |
|---|---|
Ctrl+S | Save. |
Ctrl+Z / Ctrl+Shift+Z | Undo / Redo. |
Ctrl+Enter | Test now: dry-run the workflow. |
Ctrl+D | Duplicate the selected step (Ctrl+Shift+D in the IntelliJ preset). |
Delete | Delete the selected step. |
Ctrl+↑ / Ctrl+↓ | Move the selected step up or down (Ctrl+Alt+↑ / Ctrl+Alt+↓ in the Atom preset). |
The last four act on the selected step: tap the pencil of a card to select it.
Privacy and security
Workflows run on your device; what leaves it is what you point a step at.
- Where it is stored. Definitions live in a local database on the device, one file per account. With Pro, Cloud Sync can copy the definitions between your devices (the Workflows group); runs, schedules, pinned outputs and secrets are never synced.
- Secrets. They are kept encrypted on the device, one set per account (Android Keystore key, AES-256-GCM), are never shown again, are not resolved in a dry run, don't travel in an exported file and are masked as
•••when a run is written to the history (a value shorter than 4 characters can't be masked). - Irreversible-steps permission. The answer to Enable anyway and Allow the AI is remembered on the device only, once per workflow.
- What a workflow can do. A workflow can run commands and write files with the permissions you left open; the permissions are not a sandbox, and the domain list does not stop an AI, deploy or git step.
- What leaves the device. HTTP request, Trigger deploy, Git operation (push and pull) and the AI steps go to the services you configured or the addresses you wrote. An AI step sends its prompt and context to your provider with your own key.
- Imports. A file or a link always arrives switched off, with a preview and the linter's result; a link must be
https, can't carry credentials or point at the device, doesn't follow redirects and downloads nothing until you press Download. - What other apps send you. Shared text and files arrive as data, never as instructions, and the app always shows you what was received and which workflow gets it.
- Exports. Only parameters declared as secrets are emptied; HTTP headers and commands travel as you typed them. Check the file before you share it.
Limitations
The most important limits, each with its reason. Limits specific to a screen are in the section of that screen.
- The chat can't create or change workflows on Free, and the Trigger deploy step fails on Free while a deploy of that project is already in flight.Pro
- Definitions only sync between devices with Pro (Cloud Sync).Pro
- Scheduled runs go through WorkManager: not more often than every 15 minutes, with no exact alarms, and Doze or battery saving can delay them (never cancel them).Google Play
- Runs in the background rely on a foreground service; from Android 12 the system may refuse it when the app is in the background, and the run then goes on without that protection.Google Play
- Only the first 5 simultaneous runs get a progress notification; the quick tile is opt-in and Android decides how many shortcuts a launcher shows.Device
- The secrets store may not open after you restore the phone or change the screen lock; nothing is deleted.Device
- Project closed and The AI finished its turn never fire: nothing in the app emits them.Not yet
- On git commit only fires for commits made from Projects, not for those of the editor's Source Control panel or the AI chat.Not yet
- Schedules have no time zone selector, and there is no automatic notification when a run fails.Not yet
- Workflows can't be installed from the Marketplace, and the app can't publish one.Not yet
- A run that was in flight when the system killed the app leaves no row in the history, and the shell log of a finished run isn't kept.By design
- No graph canvas, N-way switch or free merge, no editing of a schedule, no cron
?,L,#, and only three intervals as presets.By design - Up to 6 triggers per workflow, 8 conditions per filter, 8 tags per workflow, 40 steps listed in an import preview and a 512 KB file.By design
- Engine limits: 8 runs at a time across the app, 16 waiting for up to 120 seconds, 10 queued event runs per workflow, loops of up to 10 000 iterations and 16 at once, subflows 5 levels deep, a Wait for an event of 5 minutes by default, and an error message of a Try / on failure limited to 4 096 characters.By design
- Step outputs: an HTTP response body up to 128 KiB, the shell's output up to 64 KB, a file read up to 128 KiB, and each step stores at most 32 KiB of output in the history.By design
- The activity screen shows up to the 500 most recent runs; the history you keep per workflow is 1 to 1 000 runs and 1 to 365 days.By design
- Deploys go to
render,netlify,digitaloceanandrailwayonly, and Query database reachesneon,supabase,turso,upstash,cloudflare(D1) and your saved remote PostgreSQL connections.Third party - Generate from prompt and Change with AI need an AI provider with a key; without one they fall back to keyword matching.Needs network
Troubleshooting
Real messages of the app, with what they mean.
Nothing in the app emits PROJECT_CLOSED yet, so this workflow will not fire.
The trigger is in the dropdown but nothing emits it. Pick another trigger: Project closed and The AI finished its turn never fire.
No condition: this trigger fires with every event of its type.
It is not an error: the trigger has no filter. Add a condition if you want only some events.
A workflow I switched on never runs
Check that Enabled is on, that its trigger really has an emitter and a matching filter, that it isn't skipped by Skip the new one while another run is going, and that required inputs have defaults (an event, a schedule or a shortcut has nobody to ask).
No active workflow is listening for this. Add the matching trigger in the workflow editor.
You shared something to PocketCode and no switched-on workflow has Text shared to PocketCode or File shared to PocketCode. Add the trigger and switch the workflow on.
… needs a value first
A shortcut, tile or share tried to start a workflow with a required input that has no default. Give the input a default, or run it from the module.
Required with no default: … A scheduled run cannot start — the scheduler has nobody to ask.
A schedule can't ask you for inputs. Give every required input a default value.
Invalid cron expression
A cron has five fields: min hour day month weekday. ?, L, #, a step over a range and a year field are not accepted.
Asks for every 5 min, but it runs every 15 min: that is the floor Android allows.
An interval below 15 minutes is raised to 15. A cron below that rate gets “Android does not guarantee that rate in the background”.
Scheduled workflows need attention
The banner says what Android answered: Notifications are off for PocketCode, “The ‘Workflows · alerts’ channel is blocked”, or “PocketCode is subject to battery optimisation”. Tap Open settings. The banner can't be dismissed; it goes away when the cause does.
permiso denegado (…): … Se cambia en «Permisos», dentro de los ajustes del workflow.
A step was refused by the permissions of the workflow (the message is in Spanish in every language). Open Workflow settings and Permissions and open the network, writing or commands, or add the domain.
Upgrade required to trigger another active deploy
On Free a Trigger deploy step fails while a deploy of the same project is still in flight (queued, building or deploying); the limit is 1. Wait for it to finish, or go Pro.
la consulta modifica datos (…) y el paso no tiene «allowWrites» activado
A Query database step has write verbs and allowWrites is off (the message is in Spanish in every language). Turn allowWrites on only if that is what you want.
That is not a PocketCode workflow file. Pick a .pcwf.json file.
The file isn't a workflow. The other two messages are “This is a workflow file, but it is damaged and cannot be read.” and “This file was written by a newer version of PocketCode (format …). Update the app to open it.”
That address sends you somewhere else: … It was not followed — confirm the new address only if you trust it.
An import link redirected to another address. Confirm the new address only if you trust it.
The encrypted store could not be opened on this device
The secrets store can't be opened after restoring the phone or changing the screen lock. Nothing has been deleted.
Careful: this value is shorter than 4 characters, so it will NOT be masked with ••• in run history. If a step prints it, it stays readable there.
The secret is saved, but if a step prints it, it stays readable in the run history. Use a longer value.
The workflow no longer exists: this run cannot be repeated.
The workflow was deleted. Runs of a deleted workflow can still be read in Activity, but not repeated.
The shell log is not kept in the history: it is only visible while the run is going.
Follow the log from Live output while the run is going, or write what you need into a file with a step.
Fix these before saving: this workflow is not ready.
The generator's checks found an error. Open the workflow in the editor with Open in editor and fix what Problems lists.
Not tested: … You can test it yourself from the editor.
The generator didn't dry-run the workflow because a dry run executes steps and it could not be sure of one of them: a step that can't be simulated (a deploy), waits that add up to more than 10 seconds, a wait for an event, or a subflow it can't look inside. Test it from the editor.