Use the Tapicker Bridge CLI
The tapicker command manages the local Bridge service and sends commands to a connected Extension. Complete Getting Started before following these examples.
Your First Commands
With Bridge running and the Extension connected, list your Workflows:
tapicker workflow list
Copy an id from the result, then replace WORKFLOW_ID with it:
tapicker workflow start WORKFLOW_ID --watch
Single commands print JSON to standard output. Command failures print { ok: false, error: { code, message, details? } } to standard error and exit nonzero. A successful command result includes the actual Extension clientId.
Connect to the Right Bridge
Workflow and data commands accept these common options:
| Option | Purpose |
|---|---|
--url <url> | Bridge address; defaults to TAPICKER_BRIDGE_URL, then http://127.0.0.1:9520 |
--token <token> | Bearer Token; defaults to TAPICKER_BRIDGE_TOKEN |
--client-id <uuid> | Target Extension; required when more than one Extension is ready |
For a Bridge on another local port:
tapicker workflow list --url http://127.0.0.1:9521
--url accepts a base address or a copied /mcp endpoint, optionally ending in /. The endpoint is converted to the base address. Other paths, query strings, fragments, and embedded credentials are rejected.
If multiple Extensions are connected, choose a ready client's UUID and pass it to each command:
tapicker workflow list --client-id c0ffee00-0000-4000-8000-000000000001
Reuse the returned clientId when later calls must target the same browser. Local management commands such as bridge extensions use the Bridge's data directory instead of --url.
Manage the Local Service
For the first run, start Bridge in the foreground:
tapicker bridge start
For background operation, start it as a daemon:
tapicker bridge start --daemon
Use these commands on the computer running Bridge:
| Command | Purpose |
|---|---|
tapicker bridge extensions | List connected Extensions, including pending pairing connections |
tapicker bridge code | Show the current pairing code |
tapicker bridge code --refresh | Rotate the pairing code and unlock pairing |
tapicker bridge stop | Stop the running local Bridge |
A ready Extension may include a user snapshot. Use tapicker user me to get the latest account information.
Bridge uses ~/.tapicker by default. If you set --data-dir when starting it, use the same option for stop, code, and extensions. The TAPICKER_DATA_DIR environment variable also sets this directory.
bridge start --port 9520 fixes the listening port and fails if it is unavailable. Without --port, Bridge tries 9520 through 9530. For bridge start, --host selects the listening interface; client commands select the Bridge address with --url. The separate workflow list --host option filters Workflow sites. See Remote Deployment before binding to another network interface.
Find and Read Workflows
Filter your own Workflows by a substring of their full names:
tapicker workflow list --scope own --name example --page 1 --page-size 20
--scope accepts own (default), shared, or pinned. Shared includes accessible shared/public Workflows. Pagination starts at page 1, with a default page size of 20 and maximum of 100. An empty page ends the list; a full page does not guarantee another page exists. Pinned entries may refer to deleted Workflows, indicated by deletedAt.
Each entry is a summary identified by id and fullname, with intro, host, href, visibility, permission, version, revision when supported, and deletedAt. The list does not return name or nodes. Use id as workflowId for later commands, and skip deleted entries when choosing a Workflow to run or edit.
To find Workflows for one site, add --host:
tapicker workflow list --host example.com
tapicker workflow list --scope shared --host example.com --name products
--host matches the stored host exactly, without a scheme or path; a port is allowed, for example localhost:3000. example.com and www.example.com are different hosts. A site filter does not include generic Workflows whose host is *; use --host '*' to list only those. Omit --host to include all sites. Name and host filters are combined, and both apply before pagination.
Read the latest saved metadata and startup argument definitions using an id from tapicker workflow list:
tapicker workflow get WORKFLOW_ID
The result includes workflow.args, an array of startup argument definitions. With use permission, workflow.nodes is empty because the saved nodes are hidden. With view, edit, or manage permission, it contains the saved nodes.
To update the Workflow, use the returned workflow.revision and target the same Extension with --client-id.
Run and Control a Workflow
Use each argument's exact name as a key in --args and pass a value in the declared type. For example, if workflow.args includes { "name": "keyword", "type": "string" }, run:
tapicker workflow start WORKFLOW_ID --args '{"keyword":"Tapicker"}' --watch
Omit a key to use the Workflow's default. These shell examples use POSIX quoting. In other shells, pass the same JSON object using that shell's quoting rules.
Startup uses the active browser tab as its starting point. To start from a specific page, open it first or include a navigation step in the Workflow. A Workflow supports one active instance per Extension, and use-only access is sufficient to run it. Set args.isClearData to the JSON boolean true only when you intend to clear existing data in the affected tables.
The receipt contains clientId, workflowId, workflowName, runAt, and state: "accepted". With start --watch, the CLI uses that runAt to follow the run it just started. If the response is lost, check status on the same Extension before retrying. To control the run from another terminal:
tapicker workflow pause WORKFLOW_ID
tapicker workflow resume WORKFLOW_ID
tapicker workflow stop WORKFLOW_ID
Use the workflowId and, when selecting an Extension, the --client-id from the start receipt. Pause takes effect at the next pause point. Resume continues the same instance. Stop requests cancellation of a running or paused instance and succeeds when there is no active instance. Use workflow status --watch to confirm cleanup after stopping. If a command reports WorkflowStartInProgress, wait for startup before trying again.
Check Status or Wait
Get one status snapshot:
tapicker workflow status WORKFLOW_ID
The snapshot is the latest status recorded by the selected Extension. When present, runAt identifies the run. While a new run is preparing, the snapshot can still describe the previous run. If the Extension has no status record, the command returns NotFound.
After the run stops, use its runAt to read the tables it changed:
tapicker workflow status WORKFLOW_ID --include-data-summary --run-at '2026-11-04T02:30:00.000Z'
Replace the example timestamp with the observed runAt and reuse the same Extension. The summary includes changes made by child Workflows. Use its table IDs with tapicker data get.
Wait for an existing run:
tapicker workflow status WORKFLOW_ID --watch --timeout 60000
Only start and status accept --watch. Use --timeout with --watch to limit the wait in milliseconds. An already stopped run returns immediately with status --watch. If the wait reaches its time limit, the final result has isTimedOut: true and the Workflow can continue running.
Watch output is newline-delimited JSON, with one { type, data } record per line:
type | Meaning |
|---|---|
workflow.start | Start receipt, when using start --watch |
workflow.status.changed | Observed status snapshot or update |
workflow.status.watch | Final snapshot with isTimedOut: true or false |
A stopped event or final snapshot includes stopAt when recorded. Use runAt and stopAt to measure the run through cleanup.
Statuses are running, paused, stopping, and stopped. At stopped, inspect reason: only completed means success. The other reasons are failed, interrupted, workflow_stopped, and user_stopped. An unused or older status record may have no reason. Exit code 0 means the command returned normally; it does not replace checking the execution result or watch timeout.
Query Run Logs
Use logs to investigate a failure or unexpected progress:
tapicker workflow logs WORKFLOW_ID --levels warn,error --limit 100
The result contains clientId, workflowId, runAt, logs, and hasMore. List records include up to 1,024 characters of detail per entry. If detailsTruncated is true, read the full entry using its id as LOG_ID:
tapicker workflow log WORKFLOW_ID LOG_ID
| Option | Applies to | Meaning |
|---|---|---|
--levels warn,error | logs | Exact level filter; omit for all levels |
--limit 100 | logs | Page size, 1–500; default 100 |
--before LOG_ID | logs | Read older records, excluding this ID |
--after LOG_ID | logs | Read newer records, excluding this ID |
--run-at TIMESTAMP | logs, log | Require the same run as a previous result |
Supported levels are trace, debug, info, warn, and error. before and after cannot be combined. Without a cursor, the newest matching page is returned, ordered by ascending ID. Use its first ID to read older logs or its last ID to read newer logs.
Only the latest run is retained; a new run clears previous logs. Reuse clientId, a non-null runAt, and the same level filter across pages. If you receive WorkflowRunChanged, check status again before reading another page. Query logs when needed; use status watching to wait for execution.
Author Workflow JSON
Read the authoritative guide and the schema for the nodes you need:
tapicker workflow guide
tapicker workflow guide nodes/print-log
tapicker workflow schema --node-types NodePrintLog
Follow returned references.topic values with another guide command. Pass the node types you plan to use as one comma-separated --node-types value; omit it to get the schema for all supported business nodes. The result contains a draft 2020-12 JSON Schema in schema, including the definitions it needs. Schema defaults do not fill omitted fields; check generated fragments with workflow validate.
Save a node clipboard document as fragment.json:
{
"format": "tapicker/nodes",
"version": 1,
"nodes": [
{
"id": "hello",
"type": "NodePrintLog",
"config": { "level": "info", "message": "Hello from Bridge" }
}
]
}
Validate it without saving or running:
tapicker workflow validate fragment.json
Check isValid. isValid: false is a normal diagnostic result with field-level issues and exit code 0. Fix those issues before continuing. With isValid: true, nodes contains normalized copies when supplied; the input file is unchanged. Normalization can trim names, remove inapplicable fields, and apply retry defaults when retry is enabled. Pass the returned nodes directly in create or update requests. Validation does not verify real-page selectors or business outcomes.
Create a Workflow
Save the following complete request as create.json:
{
"name": "bridge-hello",
"intro": "A first Workflow created through Bridge",
"nodes": [
{
"id": "hello",
"type": "NodePrintLog",
"config": { "level": "info", "message": "Hello from Bridge" }
}
]
}
Create the private Workflow:
tapicker workflow create create.json
Creation revalidates the nodes and returns workflowId, workflowName, revision when supported, and clientId. It does not start the Workflow. Use workflow get to read it or workflow start to run it when ready.
name is trimmed and accepts 1–64 characters. intro and href default to empty strings. href accepts an absolute URL (for example, https://example.com, file:///path/to/page.html, or about:blank) or an empty string for a general-purpose Workflow. The name must be available in the selected account.
workflowName is the full name, such as @username/example. If the response is lost, list your Workflows by name in the same Extension and read matching entries to verify the content before retrying. To automate a local page, enable Allow access to file URLs in the Extension settings.
Update a Workflow
Read the latest Workflow first and copy its revision and clientId. Save an update request as update.json, replacing the example ID and revision with those you read:
{ "workflowId": "WORKFLOW_ID", "revision": 3, "intro": "Updated through Bridge" }
Submit it:
tapicker workflow update update.json --client-id c0ffee00-0000-4000-8000-000000000001
Provide at least one of name, intro, href, or nodes. Replace the example client ID with the returned clientId. Omitted fields are preserved. Set intro or href to an empty string to clear it. A non-empty href follows the same rules as creation. Supplying nodes replaces the entire node tree after validation. Update requires edit/manage permission and a server supporting revision checks. Success returns the new revision without running the Workflow or changing an active instance.
On WorkflowConflict, read the latest version, compare and reconcile your changes, then submit its revision. Replacing only the revision and retrying can overwrite someone else's work. If the response is lost, read the Workflow to check whether the changes were saved before retrying.
Pass JSON Inline or via stdin
For short requests, pass the JSON directly with --json:
tapicker workflow validate --json '{"format":"tapicker/nodes","version":1,"nodes":[{"id":"hello","type":"NodePrintLog","config":{"level":"info","message":"Hello"}}]}'
tapicker workflow create --json '{"name":"Hello","nodes":[{"id":"hello","type":"NodePrintLog","config":{"level":"info","message":"Hello"}}]}'
tapicker workflow update --json '{"workflowId":"WORKFLOW_ID","revision":3,"intro":"Updated through Bridge"}'
Each command accepts one input source. Use --json for inline JSON, a path for a JSON file, or - for stdin. Validation reads a version 1 clipboard document. Use tapicker/nodes with top-level nodes, or tapicker/workflow with a workflow object containing at least one of name, intro, href, or nodes. Creation and update read the complete request object. When multiple Extensions are ready, pass --client-id as shown above.
List, Preview, Read, Export, or Delete Extracted Data
Find a saved table by name or owning Workflow ID:
tapicker data list --table-name products
tapicker data list --workflow-id WORKFLOW_ID --page 2 --page-size 20
The default is page 1 with 20 tables, with a maximum page size of 100. Results include each table’s ordered columnNames, row count, creation and update times, and owning Workflow ID when known. Listing tables uses no export quota. If hasMore is true, request the next page with the same filters and page size.
Use the returned tableId and clientId to preview or read rows. You can also get a table ID from Copy ID in Tapicker Data.
tapicker data preview TABLE_ID
tapicker data preview TABLE_ID --sample latest
Preview returns up to 10 rows without using export quota. The default sample is oldest; latest selects the most recently inserted rows. Both samples are displayed in ascending row ID order. If the result reaches the 128 KiB limit, it includes the complete rows that fit and sets isTruncated: true.
To read more rows:
tapicker data get TABLE_ID
tapicker data get TABLE_ID --page 2 --page-size 50
tapicker data get TABLE_ID --all
The default is page 1 with 50 rows, ordered by row ID. Set --page-size to 1–500. The result includes clientId, tableId, tableName, columnNames, rowCount, and rows. In both preview and read results, rowCount is the total recorded for the table. Use rows.length for the number of returned rows. Paged results also include page, pageSize, and hasMore. Reuse --client-id and the same page size when advancing pages.
Use --all by itself to read the full table. If the result exceeds 128 KiB, use pagination or reduce the page size. Returned rows consume export quota. If the response is lost, quota may already have been deducted.
Export an entire table to a file on the machine running the CLI:
tapicker data export TABLE_ID --format xlsx --output ./products.xlsx
tapicker data export TABLE_ID --output ./exports/
Supported formats are xlsx, xls, csv, json, xml, and txt. The default is csv. Pass a new file path or an existing directory to --output. With a directory, the CLI uses the export filename and adds a number if the name is already taken. The receipt includes filename, rowCount, byteSize, a readable fileSize, and the local output path. Files over 128 MiB are rejected before quota is deducted. If downloading fails after export, use the returned downloadPath before expiresAt to retrieve the same file.
To remove a table from Tapicker Data:
tapicker data delete TABLE_ID
Verify the ID before deleting the table and all its rows. The result contains tableId, tableName, and clientId. On DataTableInUse, wait for the current operation to finish. If the response is lost, verify the table before retrying because a later Workflow run can recreate it under the same ID.
Check the Current Tapicker Account
tapicker user me
The result includes the selected clientId and user with id, username, and plan. If multiple Extensions are ready, pass --client-id to check the intended browser. An unverified email or a banned account returns EmailNotVerified or AccountBanned. Network failures and timeouts return errors.
Recover from Errors
If a start times out or its response is lost, query status before trying again: it may already be running. If creation has an uncertain outcome, list by name before retrying. For an uncertain update, read the saved Workflow first.
If a command returns SignInRequired, sign in to Tapicker in the selected Extension. Unauthorized indicates that Bridge requires its Token. Other server business errors retain their own code and message.
If no Extension is available, check its connection in Settings. If several are ready, pass --client-id. Unsupported options are rejected instead of silently ignored. Use tapicker workflow ACTION --help or tapicker data ACTION --help for action-specific options.
To configure tapicker mcp as an agent's local command, continue with MCP. For HTTP request and error formats, see HTTP.