Only these asset ids (comma-separated; any type) — single-asset export
--with-dependencies
With --ids: also export everything those assets depend on
--include-rows
Also export the rows of the exported data tables (data-rows/ folder)
--format <format>
json (default) or yaml
--force
Write into a non-empty folder, replacing files from an earlier export
bash
usertasks config export ./config --format yaml
usertasks config diff
usertasks config diff <path> — Compare a config folder or file with the workspace (a dry-run apply).
Option
Description
--exit-code
Exit 7 when there are changes or errors
--adopt-by-name
Match unmapped assets to existing ones with the same unique name
--source-label <label>
Label used for id mappings (default "default")
bash
usertasks --profile prod config diff ./config --source-label dev --exit-code
usertasks config apply
usertasks config apply <path> — Create or update assets from a config folder or file. Never deletes. ${env:VAR} and ${file:path} placeholders are substituted on your machine before upload.
Option
Description
--dry-run
Show the plan without changing anything
--adopt-by-name
Match unmapped assets to existing ones with the same unique name
--source-label <label>
Label recorded with the id mappings (default "default"); use one per source workspace
--rows-mode <mode>
Data-table rows (data-rows/): merge (default), replace or skip
bash
usertasks --profile prod config apply ./config --source-label dev
usertasks config new
usertasks config new <type> <name> — Scaffold a new asset file with a generated id. Types: workflow, decision-table, activity, data-table, integration, reference, agent, report, retention-policy, role, mcp-server.
Option
Description
--dir <dir>
Config folder (default .)
--format <format>
json or yaml
bash
usertasks config new workflow "Invoice approval" --dir ./config
Logs and events
usertasks logs tail
usertasks logs tail — Stream events live (Ctrl-C to stop). Reconnects automatically without gaps; text on a terminal, NDJSON with -o json or when piped.
usertasks workflows run <id> — Run a workflow with its input parameters. Values from -f and --input are coerced by input type; missing required inputs are asked for on a terminal (without one, they are listed and the command exits 2). Queued in the background unless --wait.
Option
Description
--input <key=value>
Input value, coerced by the input type (repeatable; wins over -f)
--wait
Run now and wait: print the run status and step outputs (exit 1 if the run failed)
--priority <n>
Queue priority 0-100 for background runs (default 50)
--task <task-id>
Associate the run with a task
bash
usertasks workflows run <id> --input customer=Acme --input amount=120 --wait
Tasks
usertasks tasks complete
usertasks tasks complete <id> — Complete a task with an outcome and field values. A workflow waiting on the task resumes.
Option
Description
--outcome <value>
Outcome, e.g. Approved or Rejected (default completed)
--notes <text>
Outcome notes
--set <field=value>
Task field value (repeatable): field=value, field:=<json>, field=@file
usertasks packages inspect <file> — Verify a .utpkg offline (checksum, every file hash, signature) and show its contents, data and requirements. Exits 6 when the file was modified.
usertasks packages install <file> — Install a package, or upgrade it in place when it is installed already: shows the plan, prompts for missing requirement values on a terminal (secrets without echo), then applies. Without a terminal, missing required values exit 6 unless --keep-incomplete.
Option
Description
--dry-run
Show the plan (diff) only
--set <assignment>
Requirement value: <requirement id>.<field key>=value (repeatable; ${env:VAR} and ${file:path} are substituted locally). Use -f values.yaml for many
--keep-incomplete
Install even if required values are missing; affected items stay disabled until packages complete
--adopt-by-name
First install: adopt existing assets with the same unique name
--data <table=mode>
Rows of a packaged data table: <table id>=merge|replace|skip (repeatable; default merge)
--allow-downgrade
Install an older version over a newer one
--source-label <label>
Where the file came from, shown in the library (default the file name)
--keep-local-changes
Upgrade: keep assets changed in this workspace since the last install
usertasks packages upgrade <file> — Upgrade an installed package in place: diff first, local requirement values kept, assets removed in the new version flagged (never deleted).
Option
Description
--dry-run
Show the plan (diff) only
--set <assignment>
Requirement value: <requirement id>.<field key>=value (repeatable; ${env:VAR} and ${file:path} are substituted locally). Use -f values.yaml for many
--keep-incomplete
Install even if required values are missing; affected items stay disabled until packages complete
--adopt-by-name
First install: adopt existing assets with the same unique name
--data <table=mode>
Rows of a packaged data table: <table id>=merge|replace|skip (repeatable; default merge)
--allow-downgrade
Install an older version over a newer one
--source-label <label>
Where the file came from, shown in the library (default the file name)
--keep-local-changes
Upgrade: keep assets changed in this workspace since the last install
usertasks packages complete <install> — Complete setup of an incomplete install (install id or package slug): supply the missing values; the items they unblock are enabled and the package workflows activated. Exits 7 while values are still missing.
usertasks packages uninstall <install> — Uninstall a package: lists what will be removed, then asks. Assets changed locally since install, and data tables that hold rows, are kept unless forced.
Option
Description
--force
Also remove assets changed in this workspace since install
usertasks packages installs — The package library: installed packages with version, status (complete / incomplete), source and signer.
bash
usertasks packages installs
Resource commands
These 190 commands are generated from the server's OpenAPI document (one per REST operation), so they always match the API. The permission column is the permission the server checks. Fields marked * are required.
activities
Command
What it does
Permission
Options
usertasks activities list
List custom workflow activities (without source code) (GET /api/v1/workflow-activities)
extensibility.view
--status draft / active / archived --search --all--limit--offset
usertasks activities create
Create a custom workflow activity (POST /api/v1/workflow-activities)
extensibility.create
body via -f / --set: name, source_code, manifest*, description, key, status, source_kind, version, icon_name, color, demo_inputs, tags, source_filename
usertasks activities import
Create an activity from a portable export (POST /api/v1/workflow-activities/import)
extensibility.create
--publish true / false body via -f / --set: workflow_activity
usertasks activities get <id>
Get an activity with source code, manifest and readiness findings (GET /api/v1/workflow-activities/{id})
extensibility.view
usertasks activities update <id>
Update an activity (omitted fields are kept) (PATCH /api/v1/workflow-activities/{id})
extensibility.edit
body via -f / --set: name, source_code, manifest, description, key, status, source_kind, version, icon_name, color, demo_inputs, tags, source_filename
usertasks activities delete <id>
Delete an activity (DELETE /api/v1/workflow-activities/{id})
extensibility.delete
asks to confirm (--yes to skip)
usertasks activities export <id>
Export an activity as portable JSON (accepted by POST /workflow-activities/import) (GET /api/v1/workflow-activities/{id}/export)
extensibility.view
agents
Command
What it does
Permission
Options
usertasks agents list
List agents (GET /api/v1/agents)
agents.view
--active true / false --all--limit--offset
usertasks agents create
Create an agent (POST /api/v1/agents)
agents.create
body via -f / --set: name*, description, model, system_prompt, role, task, boundaries, tools, output_config, integration_id, temperature, max_tokens, max_iterations
usertasks agents get <id>
Get an agent (GET /api/v1/agents/{id})
agents.view
--include-runs true / false
usertasks agents update <id>
Update an agent (PUT /api/v1/agents/{id})
agents.edit
body via -f / --set: name, description, model, system_prompt, role, task, boundaries, tools, output_config, integration_id, temperature, max_tokens, max_iterations, is_active
usertasks agents delete <id>
Delete an agent (deactivates workflows that reference it) (DELETE /api/v1/agents/{id})
agents.delete
asks to confirm (--yes to skip)
usertasks agents execute <id>
Run an agent (sync, or async via the agent queue) (POST /api/v1/agents/{id}/execute)
agents.test
body via -f / --set: message*, shared_context, async, max_iterations
usertasks agents queue
List queued agent jobs (GET /api/v1/agents/queue)
agents.view
--status --agent-id --all--limit--offset
api-keys
Command
What it does
Permission
Options
usertasks api-keys list
List API keys (never the key itself) (GET /api/v1/api-keys)
Enable a connector: creates its integration and templated references (POST /api/v1/connectors)
integrations.create
body via -f / --set: connector_key*, display_name, config, credentials
usertasks connectors get <id>
Get a connector with its template, integration and references (GET /api/v1/connectors/{id})
integrations.view
usertasks connectors update <id>
Update connector config/credentials (merged) and keep its integration in step (PATCH /api/v1/connectors/{id})
integrations.edit
body via -f / --set: display_name, config, credentials, enabled, regenerate_references
usertasks connectors delete <id>
Delete a connector, its integration and generated references (DELETE /api/v1/connectors/{id})
integrations.delete
asks to confirm (--yes to skip)
usertasks connectors test <id>
Run the connector preflight and probe with its stored credentials (POST /api/v1/connectors/{id}/test)
integrations.test
usertasks connectors enable <id>
Re-enable a connector and its integration (POST /api/v1/connectors/{id}/enable)
integrations.edit
usertasks connectors disable <id>
Disable a connector and deactivate its integration (POST /api/v1/connectors/{id}/disable)
integrations.edit
usertasks connectors regenerate-references <id>
Replace the generated references with the current template set (POST /api/v1/connectors/{id}/regenerate-references)
integrations.manage_references
decision-tables
Command
What it does
Permission
Options
usertasks decision-tables list
List decision tables (GET /api/v1/decision-tables)
workflows.view
--search --all--limit--offset
usertasks decision-tables create
Create a decision table (POST /api/v1/decision-tables)
workflows.edit
body via -f / --set: name*, description, inputs, outputs, rules
usertasks decision-tables get <id>
Get a decision table (GET /api/v1/decision-tables/{id})
workflows.view
usertasks decision-tables update <id>
Update a decision table (omitted fields are kept) (PUT /api/v1/decision-tables/{id})
workflows.edit
body via -f / --set: name, description, inputs, outputs, rules
usertasks decision-tables delete <id>
Delete a decision table (queued) (DELETE /api/v1/decision-tables/{id})
workflows.delete
asks to confirm (--yes to skip)
usertasks decision-tables test <id>
Evaluate a decision table against input values (POST /api/v1/decision-tables/{id}/test)
workflows.view
body via -f / --set: values
usertasks decision-tables export <id>
Export a decision table as portable JSON (GET /api/v1/decision-tables/{id}/export)
workflows.view
usertasks decision-tables import
Create a decision table from an export document (POST /api/v1/decision-tables/import)
workflows.create
body via -f / --set: decision_table, name, name_override, description_override
directory-sync
Command
What it does
Permission
Options
usertasks directory-sync list
List directory connections (Entra ID, Okta, LDAP, Google Workspace, SCIM) with sync state (GET /api/v1/directory-sync/connections)
settings.view
usertasks directory-sync connect
Connect a directory (the connection is verified before it is saved) (POST /api/v1/directory-sync/connections)
settings.edit
body via -f / --set: provider*, settings, credentials, sync_groups, auto_provision
usertasks directory-sync get <provider>
Get a directory connection (credentials masked) (GET /api/v1/directory-sync/connections/{provider})
settings.view
usertasks directory-sync update <provider>
Update a directory connection (re-verified when settings or credentials change) (PATCH /api/v1/directory-sync/connections/{provider})
settings.edit
body via -f / --set: provider, settings, credentials, sync_groups, auto_provision
usertasks directory-sync disconnect <provider>
Disconnect a directory: syncing stops and credentials are removed (SCIM: every token is revoked). Links and accounts are kept. (DELETE /api/v1/directory-sync/connections/{provider})
settings.edit
asks to confirm (--yes to skip)
usertasks directory-sync test <provider>
Test a directory connection (optionally with unsaved settings/credentials) (POST /api/v1/directory-sync/connections/{provider}/test)
settings.edit
body via -f / --set: settings, credentials
usertasks directory-sync sync <provider>
Start a sync run now (runs in the background) (POST /api/v1/directory-sync/connections/{provider}/sync)
settings.edit
body via -f / --set: full
usertasks directory-sync runs
List directory sync runs, newest first (GET /api/v1/directory-sync/runs)
settings.view
--provider entra / okta / ldap / google --all--limit--offset
email-templates
Command
What it does
Permission
Options
usertasks email-templates list
List email templates (without bodies) (GET /api/v1/email-templates)
workflows.view
--search --all--limit--offset
usertasks email-templates create
Create an email template (POST /api/v1/email-templates)
workflows.create
body via -f / --set: name, description, subject, html_body*, text_body, is_default
usertasks email-templates get <id>
Get an email template with its subject and bodies (GET /api/v1/email-templates/{id})
workflows.view
usertasks email-templates update <id>
Update an email template (PATCH /api/v1/email-templates/{id})
workflows.edit
body via -f / --set: name, description, subject, html_body, text_body, is_default
usertasks email-templates delete <id>
Delete an email template (409 for the default template) (DELETE /api/v1/email-templates/{id})
workflows.edit
asks to confirm (--yes to skip)
usertasks email-templates preview <id>
Render the subject and bodies with sample variables (nothing is sent) (POST /api/v1/email-templates/{id}/preview)
workflows.view
body via -f / --set: variables, task
events
Command
What it does
Permission
Options
usertasks events complete <id>
Resume a run waiting on an external event (POST /api/v1/workflows/events/{id}/complete)
workflows.activate
body via -f / --set: return_variables
usertasks events list
List events from the unified event stream (oldest first, cursor paged) (GET /api/v1/events)
Get a workflow run with its logs (GET /api/v1/workflows/runs/{id})
workflows.view_runs
usertasks runs action <id>
Pause, resume or cancel a run (POST /api/v1/workflows/runs/{id}/action)
workflows.activate
body via -f / --set: action*, return_variables, goto_node_id
scim-tokens
Command
What it does
Permission
Options
usertasks scim-tokens list
List SCIM tokens (never the tokens themselves) (GET /api/v1/directory-sync/scim-tokens)
settings.view
usertasks scim-tokens create
Create a SCIM token for the identity provider (shown once); enables SCIM provisioning (POST /api/v1/directory-sync/scim-tokens)
settings.edit
body via -f / --set: name*, scopes, expires_in_days
usertasks scim-tokens delete <id>
Revoke and delete a SCIM token (DELETE /api/v1/directory-sync/scim-tokens/{id})
settings.edit
asks to confirm (--yes to skip)
usertasks scim-tokens rotate <id>
Replace a SCIM token with a new one (same name and scopes); the old one stops working now or after grace_minutes (POST /api/v1/directory-sync/scim-tokens/{id}/rotate)
settings.edit
body via -f / --set: grace_minutes
tables
Command
What it does
Permission
Options
usertasks tables list
List data tables (GET /api/v1/data-tables)
data.view
--search --all--limit--offset
usertasks tables create
Create a data table (POST /api/v1/data-tables)
data.create
body via -f / --set: name*, description, columns
usertasks tables get <id>
Get a data table with its columns (GET /api/v1/data-tables/{id})
data.view
usertasks tables update <id>
Rename a data table or replace its custom columns (PATCH /api/v1/data-tables/{id})
data.edit_schema
body via -f / --set: name, description, columns
usertasks tables delete <id>
Delete a data table and all its rows (queued) (DELETE /api/v1/data-tables/{id})