Control Tapicker Workflows from the CLI

After Bridge is running and an Extension is ready, you can control a Workflow from any terminal that can reach the Bridge.

Find the Workflow ID

Use Tapicker’s Copy ID action on the Workflow you want to run. The Workflow ID is different from its display name; use the ID in Bridge commands.

Start a Workflow

tapicker workflow start <workflowId> [options]

For example, pass Workflow arguments as a JSON object and wait for status updates:

tapicker workflow start jr657xeb \
  --args '{"keyword":"Tapicker"}' \
  --watch

The Workflow engine selects and prepares the browser tab.

The start response includes the workflowId, full workflowName, and selected clientId. It confirms startup was accepted, not that execution succeeded; use --watch to observe the result. If the start response times out or the connection closes, query workflow status before retrying because the Workflow may already be running.

Control a Running Workflow

Use the same Workflow ID to control its active instance:

tapicker workflow pause jr657xeb
tapicker workflow resume jr657xeb
tapicker workflow stop jr657xeb

The Extension currently allows one active instance of a given Workflow. Bridge does not start a second instance of the same Workflow in that Extension.

Check Status or Watch Updates

Get one status snapshot:

tapicker workflow status jr657xeb

Watch an already-started Workflow:

tapicker workflow status jr657xeb --watch

Or start and watch in one command:

tapicker workflow start jr657xeb --watch

With status --watch, the CLI subscribes before querying a status snapshot. An already stopped snapshot returns immediately, and this command never starts a Workflow. --watch is valid only for start and status; --timeout requires --watch.

The watch commands stream updates until the Workflow has status: "stopped". Its reason is failed, completed, interrupted, workflow_stopped, or user_stopped. Only completed means successful execution. A successful stop response acknowledges the request; cleanup finishes when the status becomes stopped. Add --timeout <milliseconds> to limit how long the CLI waits. A timeout or Ctrl+C ends the watch only; it does not stop the Workflow. For reconnect behavior and the raw WebSocket protocol, see Workflow status events.

Query Run Logs

Read the newest matching log page, or read a selected log with full details:

tapicker workflow logs jr657xeb --levels warn,error --limit 100
tapicker workflow logs jr657xeb --before 1234
tapicker workflow logs jr657xeb --after 1234
tapicker workflow log jr657xeb 1234

levels matches the specified levels exactly: trace, debug, info, warn, error. Omit it to include all levels. Filtering happens before pagination; limit defaults to 100 and accepts 1–500. Without a cursor, logs returns the newest matching page. Every page is ordered by ascending ID. before reads the nearest older page, after reads the next newer page; both exclude the cursor ID and cannot be combined.

The list response is { workflowId, runAt, logs, hasMore }. hasMore indicates additional matches in the requested direction at query time. Each log includes its ID, timestamp, level, message, optional node information, optional detailsText, and detailsTruncated. When details are truncated, use workflow log to read { workflowId, runAt, log } with full readable details.

Only the latest run is retained, and a new run clears old logs. Both commands accept optional --run-at <timestamp> to compare with process.runAt; a mismatch returns WorkflowRunChanged. Responses always include runAt, which may be null for a process that has not run. Missing processes or cleared logs return NotFound. Running queries read persisted entries, so new logs may take about 500 ms to appear.

Use logs on demand to investigate failures or progress. The execution outcome still comes from status and reason.

Choose an Extension

If exactly one ready Extension is connected, Bridge selects it automatically. If multiple Extensions are ready, first list them:

tapicker bridge extensions

Then pass the intended Extension’s clientId:

tapicker workflow start jr657xeb \
  --client-id 56a450e6-41f1-448e-9ea7-a2d958cbda37

The same --client-id option is available for pause, resume, stop, status, watch, logs, log, and data commands. Bridge does not broadcast a Workflow command to every connected Extension.