CLI, SDK and config

Command reference

Every usertasks command, option and exit code — generated from the CLI command table and the hand-written commands.

Run usertasks <resource> --help or usertasks <resource> <verb> --help for the same information in your terminal.

Global options

OptionDescription
--profile <name>Profile to use (env USERTASKS_PROFILE)
--url <url>Server URL (env USERTASKS_URL)
-o, --output <format>table, json or yaml (env USERTASKS_OUTPUT; table on a terminal, json otherwise; text = table)
-f, --file <path>Request body from a JSON or YAML file, or - for stdin
--allFetch every page of a list
--limit <n>Page size for list commands
--offset <n>Rows to skip for list commands
-y, --yesDo not prompt for confirmation (destructive commands prompt on a terminal)
--quietSuppress informational messages
--debugLog HTTP requests to stderr
-v, --versionPrint the CLI version
-h, --helpHelp for any command or resource

Exit codes

CodeMeaning
0OK
1Error
2Usage error
3Unauthenticated (log in again, or check USERTASKS_API_KEY)
4Forbidden (missing permission or OAuth scope)
5Not found
6Validation error or conflict
7Config changes found (diff --exit-code) or apply errors
8Rate limited
10Network or server error

Sign-in and profiles

usertasks login

usertasks login — Log in to a UserTasks server (browser login with OAuth and PKCE, or an API key) and save it as a profile.

OptionDescription
--api-key [key]Store an API key instead: a value, - for stdin, or omit to be prompted
--scopes <scopes>OAuth scopes to request, comma or space separated (default: every scope except keys:write)
--no-browserPrint the login URL instead of opening a browser
bash
usertasks login --url https://tasks.example.com --profile prod

usertasks logout

usertasks logout — Remove the stored credential from a profile; browser logins are revoked on the server.

bash
usertasks logout --profile prod

usertasks whoami

usertasks whoami — Show the workspace, user, auth kind, permissions, scopes and expiry of the active credential.

bash
usertasks whoami -o yaml

usertasks profiles list

usertasks profiles list — List saved profiles (credentials are never shown).

usertasks profiles use

usertasks profiles use <name> — Make a profile the default.

bash
usertasks profiles use prod

usertasks profiles rm

usertasks profiles rm <name> — Delete a profile and its stored credential.

Config as code

usertasks config export

usertasks config export <dir> — Export workspace configuration into a folder (the GitHub sync layout). Secrets are replaced by "__SECRET__".

OptionDescription
--types <list>Sections to export: workflows, decision_tables, workflow_activities, data_tables, integrations, agents, reports, retention_policies, roles, mcp_servers, email_templates, connectors, log_destinations, workspace_theme
--ids <list>Only these asset ids (comma-separated; any type) — single-asset export
--with-dependenciesWith --ids: also export everything those assets depend on
--include-rowsAlso export the rows of the exported data tables (data-rows/ folder)
--format <format>json (default) or yaml
--forceWrite 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).

OptionDescription
--exit-codeExit 7 when there are changes or errors
--adopt-by-nameMatch 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.

OptionDescription
--dry-runShow the plan without changing anything
--adopt-by-nameMatch 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.

OptionDescription
--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.

OptionDescription
--category <list>Categories, comma-separated: workflow, integration, agent, task, system, audit, security
--type <list>Event types or globs, comma-separated ("workflow.", ".failed")
--severity <level>Minimum severity: debug, info, warn, error
--workflow <id>Only events of this workflow
--run <id>Only events of this workflow run
--task <id>Only events of this task
--trace <id>Only events with this trace id
--since <when>Start from an ISO time or a duration back (30s, 15m, 1h); default: from now
--after <id>Start after this event id
bash
usertasks logs tail --category workflow,integration --severity warn

usertasks logs export

usertasks logs export — Write past events as NDJSON (one event per line) to stdout.

OptionDescription
--category <list>Categories, comma-separated: workflow, integration, agent, task, system, audit, security
--type <list>Event types or globs, comma-separated ("workflow.", ".failed")
--severity <level>Minimum severity: debug, info, warn, error
--workflow <id>Only events of this workflow
--run <id>Only events of this workflow run
--task <id>Only events of this task
--trace <id>Only events with this trace id
--since <when>From an ISO time or a duration back (30s, 15m, 1h, 2d)
--until <when>Up to an ISO time or a duration back
--after <id>Only events after this id (instead of --since)
bash
usertasks logs export --since 24h --category audit,security > audit.ndjson

Workflows

usertasks workflows run

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.

OptionDescription
--input <key=value>Input value, coerced by the input type (repeatable; wins over -f)
--waitRun 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.

OptionDescription
--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
bash
usertasks tasks complete <task-id> --outcome Approved --set cost_centre=OPS --set amount:=1200

Utilities

usertasks api

usertasks api <method> <path> — Make an authenticated request to any /api/v1 path and print the raw JSON response.

OptionDescription
-q, --query <key=value>Query parameter (repeatable)
--set <assignment>Body field (repeatable): key=value, key:=<json>, key=@file (text), key:=@file (JSON/YAML)
bash
usertasks api GET /workflows -q limit=5

usertasks completion

usertasks completion <shell> — Print a shell completion script for bash, zsh or fish.

bash
usertasks completion zsh > "${fpath[1]}/_usertasks"

Packages

usertasks packages add

usertasks packages add <package> <refs...> — Add artifacts (<type>:<id>, e.g. data_table:3fa8…) and everything they use to a package.

OptionDescription
--rows <table-id>Package this data table with its rows (repeatable)
bash
usertasks packages add invoice-approval data_table:3fa8c21b-… --rows 3fa8c21b-…

usertasks packages remove

usertasks packages remove <package> <refs...> — Leave artifacts (<type>:<id>) out of a package.

bash
usertasks packages remove invoice-approval email_template:…

usertasks packages build

usertasks packages build <package> — Build, sign and publish a new version and save the .utpkg file (POST /packages/{id}/versions).

OptionDescription
--release <version>Exact semantic version, e.g. 1.2.0 (default: bump the latest)
--bump <kind>major, minor or patch (default patch)
--notes <text>Release notes
--out <file>Where to save the file (default <slug>-<version>.utpkg)
-O <file>Alias of --out
bash
usertasks packages build invoice-approval --bump minor --out invoice-approval.utpkg

usertasks packages download

usertasks packages download <package> [version] — Download a built version (default latest) as a .utpkg file.

OptionDescription
--out <file>Where to save the file
bash
usertasks packages download invoice-approval 1.1.0

usertasks packages inspect

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.

bash
usertasks packages inspect invoice-approval-1.1.0.utpkg

usertasks packages install

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.

OptionDescription
--dry-runShow 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-incompleteInstall even if required values are missing; affected items stay disabled until packages complete
--adopt-by-nameFirst 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-downgradeInstall 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-changesUpgrade: keep assets changed in this workspace since the last install
bash
usertasks packages install invoice-approval-1.1.0.utpkg -f values.yaml --set 'connector:connectors:<id>.credentials.password=${env:DB_PASSWORD}' --yes

usertasks packages upgrade

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).

OptionDescription
--dry-runShow 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-incompleteInstall even if required values are missing; affected items stay disabled until packages complete
--adopt-by-nameFirst 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-downgradeInstall 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-changesUpgrade: keep assets changed in this workspace since the last install
bash
usertasks packages upgrade invoice-approval-1.2.0.utpkg --dry-run

usertasks packages complete

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.

OptionDescription
--set <assignment>Requirement value: <requirement id>.<field key>=value (repeatable)
--dry-runShow what is still missing
bash
usertasks packages complete invoice-approval --set 'integration_auth:integrations:<id>.config.auth_config.token=${env:ERP_TOKEN}'

usertasks packages uninstall

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.

OptionDescription
--forceAlso remove assets changed in this workspace since install
--delete-dataAlso delete data tables that hold rows
--dry-runList only
bash
usertasks packages uninstall invoice-approval --dry-run

usertasks packages installs

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

CommandWhat it doesPermissionOptions
usertasks activities listList custom workflow activities (without source code) (GET /api/v1/workflow-activities)extensibility.view--status draft / active / archived
--search
--all --limit --offset
usertasks activities createCreate a custom workflow activity (POST /api/v1/workflow-activities)extensibility.createbody via -f / --set: name, source_code, manifest*, description, key, status, source_kind, version, icon_name, color, demo_inputs, tags, source_filename
usertasks activities importCreate 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.editbody 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.deleteasks 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

CommandWhat it doesPermissionOptions
usertasks agents listList agents (GET /api/v1/agents)agents.view--active true / false
--all --limit --offset
usertasks agents createCreate an agent (POST /api/v1/agents)agents.createbody 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.editbody 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.deleteasks 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.testbody via -f / --set: message*, shared_context, async, max_iterations
usertasks agents queueList queued agent jobs (GET /api/v1/agents/queue)agents.view--status
--agent-id
--all --limit --offset

api-keys

CommandWhat it doesPermissionOptions
usertasks api-keys listList API keys (never the key itself) (GET /api/v1/api-keys)settings.manage_api_keys--include-revoked true / false
--all --limit --offset
usertasks api-keys createCreate an API key (the key is shown once) (POST /api/v1/api-keys)settings.manage_api_keysbody via -f / --set: name*, key_type, user_id, permissions, workflow_ids, table_ids, expires_in_days
usertasks api-keys revoke <id>Revoke an API key (kept for history, stops authenticating) (POST /api/v1/api-keys/{id}/revoke)settings.manage_api_keysasks to confirm (--yes to skip)
usertasks api-keys delete <id>Delete an API key (DELETE /api/v1/api-keys/{id})settings.manage_api_keysasks to confirm (--yes to skip)

audit-log

CommandWhat it doesPermissionOptions
usertasks audit-log listQuery the object audit log (newest first) (GET /api/v1/audit-log)settings.view--object-type
--object-id
--actor-id
--action
--from
--to
--all --limit --offset

connectors

CommandWhat it doesPermissionOptions
usertasks connectors catalogList the built-in connector templates (GET /api/v1/connectors/catalog)integrations.view--category cloud / communication / ai / payments / productivity / database
usertasks connectors listList enabled connectors (credentials masked) (GET /api/v1/connectors)integrations.view--enabled true / false
--connector-key
--all --limit --offset
usertasks connectors createEnable a connector: creates its integration and templated references (POST /api/v1/connectors)integrations.createbody 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.editbody 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.deleteasks 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

CommandWhat it doesPermissionOptions
usertasks decision-tables listList decision tables (GET /api/v1/decision-tables)workflows.view--search
--all --limit --offset
usertasks decision-tables createCreate a decision table (POST /api/v1/decision-tables)workflows.editbody 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.editbody 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.deleteasks 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.viewbody 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 importCreate a decision table from an export document (POST /api/v1/decision-tables/import)workflows.createbody via -f / --set: decision_table, name, name_override, description_override

directory-sync

CommandWhat it doesPermissionOptions
usertasks directory-sync listList directory connections (Entra ID, Okta, LDAP, Google Workspace, SCIM) with sync state (GET /api/v1/directory-sync/connections)settings.view
usertasks directory-sync connectConnect a directory (the connection is verified before it is saved) (POST /api/v1/directory-sync/connections)settings.editbody 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.editbody 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.editasks 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.editbody 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.editbody via -f / --set: full
usertasks directory-sync runsList directory sync runs, newest first (GET /api/v1/directory-sync/runs)settings.view--provider entra / okta / ldap / google
--all --limit --offset

email-templates

CommandWhat it doesPermissionOptions
usertasks email-templates listList email templates (without bodies) (GET /api/v1/email-templates)workflows.view--search
--all --limit --offset
usertasks email-templates createCreate an email template (POST /api/v1/email-templates)workflows.createbody 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.editbody 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.editasks 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.viewbody via -f / --set: variables, task

events

CommandWhat it doesPermissionOptions
usertasks events complete <id>Resume a run waiting on an external event (POST /api/v1/workflows/events/{id}/complete)workflows.activatebody via -f / --set: return_variables
usertasks events listList events from the unified event stream (oldest first, cursor paged) (GET /api/v1/events)observability.view--category
--type
--severity debug / info / warn / error
--workflow-id
--run-id
--task-id
--trace-id
--since
--after
--until
--limit --after

github-sync

CommandWhat it doesPermissionOptions
usertasks github-sync statusConnection status, pending changes and latest run/deployment (GET /api/v1/github-sync/status)sync.view
usertasks github-sync commitCommit pending changes to the repository (POST /api/v1/github-sync/commit)sync.managebody via -f / --set: message
usertasks github-sync runsList sync runs (GET /api/v1/github-sync/runs)sync.view--status
--kind
--all --limit --offset
usertasks github-sync syncEnqueue a full, pending-change or scoped sync (POST /api/v1/github-sync/runs)sync.managebody via -f / --set: kind, scope, message
usertasks github-sync run <id>Get a sync run (GET /api/v1/github-sync/runs/{id})sync.view
usertasks github-sync deployDeploy the repository manifest into this workspace (POST /api/v1/github-sync/deploy)sync.deploybody via -f / --set: dry_run, commit_sha, ref
usertasks github-sync deploymentsList deployments (GET /api/v1/github-sync/deployments)sync.view--all --limit --offset
usertasks github-sync deployment <id>Get a deployment (GET /api/v1/github-sync/deployments/{id})sync.view
usertasks github-sync scheduleGet the scheduled sync configuration (GET /api/v1/github-sync/schedule)sync.view
usertasks github-sync set-scheduleSet the scheduled sync configuration (PUT /api/v1/github-sync/schedule)sync.managebody via -f / --set: schedule
usertasks github-sync unscheduleDisable scheduled sync (DELETE /api/v1/github-sync/schedule)sync.manageasks to confirm (--yes to skip)

integrations

CommandWhat it doesPermissionOptions
usertasks integrations listList integrations (GET /api/v1/integrations)integrations.view--active true / false
--type
--search
--all --limit --offset
usertasks integrations createCreate an integration (credentials are encrypted at rest) (POST /api/v1/integrations)integrations.createbody via -f / --set: name, type, config*, tags
usertasks integrations import-openapiCreate an integration with one reference per operation from an OpenAPI 2/3 or Postman document (POST /api/v1/integrations/import-openapi)integrations.create--name
--base-url
--auth-type none / api_key / bearer / basic
body via -f / --set: spec, name, base_url, auth_type, auth_config, selected_reference_indexes, tags
usertasks integrations get <id>Get an integration (masked config) with its references (GET /api/v1/integrations/{id})integrations.view
usertasks integrations update <id>Update an integration (PATCH /api/v1/integrations/{id})integrations.editbody via -f / --set: name, config, is_active, tags
usertasks integrations delete <id>Delete an integration and its references (DELETE /api/v1/integrations/{id})integrations.deleteasks to confirm (--yes to skip)
usertasks integrations test <id>Test the connection (GET base URL with the configured auth) (POST /api/v1/integrations/{id}/test)integrations.test

invitations

CommandWhat it doesPermissionOptions
usertasks invitations listList invitations (pending by default) (GET /api/v1/invitations)team.invite--status pending / all
--all --limit --offset
usertasks invitations sendInvite someone to the workspace by email (POST /api/v1/invitations)team.invitebody via -f / --set: email*, role
usertasks invitations revoke <id>Revoke an invitation (its link stops working) (DELETE /api/v1/invitations/{id})team.inviteasks to confirm (--yes to skip)
usertasks invitations resend <id>Email a pending invitation again with a fresh link and expiry (POST /api/v1/invitations/{id}/resend)team.invite

log-destinations

CommandWhat it doesPermissionOptions
usertasks log-destinations listList log export destinations (credentials masked) (GET /api/v1/log-destinations)observability.view--all --limit --offset
usertasks log-destinations createCreate a log export destination (Splunk HEC, Datadog, OTLP/HTTP, webhook, syslog, Azure Monitor, Event Hubs, Cloud Logging, Pub/Sub) (POST /api/v1/log-destinations)settings.editbody via -f / --set: name, type, config*, credentials, filters, enabled, start_from
usertasks log-destinations get <id>Get a log export destination (credentials masked) (GET /api/v1/log-destinations/{id})observability.view
usertasks log-destinations update <id>Update a log export destination (PATCH /api/v1/log-destinations/{id})settings.editbody via -f / --set: name, type, config, credentials, filters, enabled
usertasks log-destinations delete <id>Delete a log export destination (DELETE /api/v1/log-destinations/{id})settings.editasks to confirm (--yes to skip)
usertasks log-destinations reset-cursor <id>Move a destination's cursor to now or to the start of retention (POST /api/v1/log-destinations/{id}/reset-cursor)settings.editbody via -f / --set: from*
usertasks log-destinations status <id>Delivery status of a destination: lag, last success and last error (GET /api/v1/log-destinations/{id}/status)observability.view
usertasks log-destinations test <id>Send one synthetic system.test event through the destination's formatter and connection (POST /api/v1/log-destinations/{id}/test)settings.edit

me

CommandWhat it doesPermissionOptions
usertasks me getDescribe the calling credential: tenant, user, auth kind and permissions (GET /api/v1/me)any

objects

CommandWhat it doesPermissionOptions
usertasks objects listList composite objects with their sources (GET /api/v1/objects)integrations.view--all --limit --offset
usertasks objects createCreate a composite object (also generates its callable reference) (POST /api/v1/objects)integrations.editbody via -f / --set: name, description, sources
usertasks objects get <id>Get a composite object with its sources and generated references (GET /api/v1/objects/{id})integrations.view
usertasks objects update <id>Update a composite object (name, description, or a full replacement source list) (PATCH /api/v1/objects/{id})integrations.editbody via -f / --set: name, description, sources
usertasks objects delete <id>Delete a composite object, its sources and generated references (DELETE /api/v1/objects/{id})integrations.deleteasks to confirm (--yes to skip)

package-installs

CommandWhat it doesPermissionOptions
usertasks package-installs listThe package library: installed packages with version, source and status (GET /api/v1/package-installs)packages.view--all --limit --offset
usertasks package-installs get <id>An installed package: requirement checklist and installed assets (GET /api/v1/package-installs/{id})packages.view

packages

CommandWhat it doesPermissionOptions
usertasks packages listList packages authored in this workspace (GET /api/v1/packages)packages.view--all --limit --offset
usertasks packages createCreate a package from root artifacts (dependencies are included automatically) (POST /api/v1/packages)packages.managebody via -f / --set: name, slug, description, author, icon, readme, roots, items, excluded, data_modes, package_uid
usertasks packages previewPreview what a package of these roots would contain (dependencies and requirements) (POST /api/v1/packages/preview)packages.viewbody via -f / --set: roots*, items, excluded, data_modes
usertasks packages get <id>Get a package and its recent versions (GET /api/v1/packages/{id})packages.view
usertasks packages update <id>Update a package (metadata, items, data modes) (PATCH /api/v1/packages/{id})packages.managebody via -f / --set: name, slug, description, author, icon, readme, roots, items, excluded, add, remove, data_modes
usertasks packages delete <id>Delete a package and its built versions (installs elsewhere are unaffected) (DELETE /api/v1/packages/{id})packages.manageasks to confirm (--yes to skip)
usertasks packages contents <id>What the package contains now: artifacts (and why), data modes, requirements (GET /api/v1/packages/{id}/contents)packages.view
usertasks packages versions <id>List built versions of a package (GET /api/v1/packages/{id}/versions)packages.view--all --limit --offset
usertasks packages version <id> <versionId>Get a built version (its manifest: requirements, files, checksum, signature) (GET /api/v1/packages/{id}/versions/{versionId})packages.view

queue

CommandWhat it doesPermissionOptions
usertasks queue listList queued workflow jobs (GET /api/v1/workflows/queue)workflows.view_runs--workflow-id
--status
--all --limit --offset
usertasks queue action <id>Cancel or retry a queued job (POST /api/v1/workflows/queue/{id}/action)workflows.activatebody via -f / --set: action*

references

CommandWhat it doesPermissionOptions
usertasks references list <id>List an integration's references (GET /api/v1/integrations/{id}/references)integrations.view--search
--all --limit --offset
usertasks references create <id>Create a reference on an integration (POST /api/v1/integrations/{id}/references)integrations.manage_referencesbody via -f / --set: name*, description, method, path_template, body_template, headers, query_params, request_config, inputs, outputs, response_schema, tags
usertasks references get <id>Get a reference (request config, inputs, outputs, response model) (GET /api/v1/references/{id})integrations.view
usertasks references update <id>Update a reference (PATCH /api/v1/references/{id})integrations.manage_referencesbody via -f / --set: name, description, method, request_config, inputs, outputs, response_schema, tags
usertasks references delete <id>Delete a reference (DELETE /api/v1/references/{id})integrations.manage_referencesasks to confirm (--yes to skip)
usertasks references bulk-deleteDelete several references (ids outside the workspace are ignored) (POST /api/v1/references/bulk-delete)integrations.manage_referencesbody via -f / --set: ids*
asks to confirm (--yes to skip)
usertasks references execute <id>Call a reference with input values (POST /api/v1/references/{id}/execute)integrations.testbody via -f / --set: inputs, capture_schema

reports

CommandWhat it doesPermissionOptions
usertasks reports listList saved reports (GET /api/v1/reports)reports.view--shared true / false
--category
--all --limit --offset
usertasks reports createCreate a saved report (POST /api/v1/reports)reports.createbody via -f / --set: name*, description, category, is_shared, config
usertasks reports get <id>Get a saved report (GET /api/v1/reports/{id})reports.view
usertasks reports update <id>Update a saved report (PUT /api/v1/reports/{id})reports.edit_ownbody via -f / --set: name, description, category, is_shared, config
usertasks reports delete <id>Delete a saved report (DELETE /api/v1/reports/{id})reports.deleteasks to confirm (--yes to skip)
usertasks reports previewRun a report configuration without saving it (POST /api/v1/reports/preview)reports.viewbody via -f / --set: data_source*
usertasks reports sourcesList report data sources (GET /api/v1/reports/sources)reports.view
usertasks reports export <id>Export a saved report as portable JSON (GET /api/v1/reports/{id}/export)reports.view
usertasks reports importCreate a saved report from an export document (POST /api/v1/reports/import)reports.createbody via -f / --set: report, name, name_override

retention

CommandWhat it doesPermissionOptions
usertasks retention listList retention policies (GET /api/v1/retention-policies)settings.view--search
--applies-to
--policy-mode
--all --limit --offset
usertasks retention createCreate a retention policy (POST /api/v1/retention-policies)settings.editbody via -f / --set: name, description, policy_mode, duration_value, duration_unit, exact_date, applies_to
usertasks retention get <id>Get a retention policy (GET /api/v1/retention-policies/{id})settings.view
usertasks retention update <id>Update a retention policy (PUT /api/v1/retention-policies/{id})settings.editbody via -f / --set: name, description, policy_mode, duration_value, duration_unit, exact_date, applies_to
usertasks retention delete <id>Delete a retention policy (DELETE /api/v1/retention-policies/{id})settings.editasks to confirm (--yes to skip)
usertasks retention assets <id>List assets governed by a retention policy (GET /api/v1/retention-policies/{id}/assets)settings.view
usertasks retention assignAssign (or clear) the retention policy on an asset (POST /api/v1/retention-policies/assign)settings.editbody via -f / --set: target_type, target_id, retention_policy_id

roles

CommandWhat it doesPermissionOptions
usertasks roles listList system and custom roles with their permissions (GET /api/v1/roles)team.view_members
usertasks roles createCreate a custom role (POST /api/v1/roles)team.change_rolesbody via -f / --set: name*, description, permissions
usertasks roles get <id>Get a role (GET /api/v1/roles/{id})team.view_members
usertasks roles update <id>Update a role (PATCH /api/v1/roles/{id})team.change_rolesbody via -f / --set: name, description, permissions
usertasks roles delete <id>Delete a custom role (its assignments are removed; 409 for system roles) (DELETE /api/v1/roles/{id})team.change_rolesasks to confirm (--yes to skip)

rows

CommandWhat it doesPermissionOptions
usertasks rows list <id>List or search rows (GET /api/v1/data-tables/{id}/rows)data.view--search
--filters
--order
--all --limit --offset
usertasks rows upsert <id>Insert rows, or replace existing ones by row_id (single or bulk) (POST /api/v1/data-tables/{id}/rows)data.manage_rowsbody via -f / --set: row_id, data, rows
usertasks rows get <id> <rowId>Get a row (GET /api/v1/data-tables/{id}/rows/{rowId})data.view
usertasks rows update <id> <rowId>Change cells of a row (others are kept) (PATCH /api/v1/data-tables/{id}/rows/{rowId})data.manage_rowsbody via -f / --set: data*
usertasks rows delete <id> <rowId>Delete a row (queued; fires data_table_event "deleted" workflows) (DELETE /api/v1/data-tables/{id}/rows/{rowId})data.manage_rowsasks to confirm (--yes to skip)
usertasks rows bulk-delete <id>Delete up to 500 rows of a table (queued); unknown ids are ignored (POST /api/v1/data-tables/{id}/rows/bulk-delete)data.manage_rowsbody via -f / --set: row_ids*
asks to confirm (--yes to skip)

runs

CommandWhat it doesPermissionOptions
usertasks runs listList workflow runs (GET /api/v1/workflows/runs)workflows.view_runs--workflow-id
--version-id
--status
--all --limit --offset
usertasks runs get <id>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.activatebody via -f / --set: action*, return_variables, goto_node_id

scim-tokens

CommandWhat it doesPermissionOptions
usertasks scim-tokens listList SCIM tokens (never the tokens themselves) (GET /api/v1/directory-sync/scim-tokens)settings.view
usertasks scim-tokens createCreate a SCIM token for the identity provider (shown once); enables SCIM provisioning (POST /api/v1/directory-sync/scim-tokens)settings.editbody 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.editasks 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.editbody via -f / --set: grace_minutes

tables

CommandWhat it doesPermissionOptions
usertasks tables listList data tables (GET /api/v1/data-tables)data.view--search
--all --limit --offset
usertasks tables createCreate a data table (POST /api/v1/data-tables)data.createbody 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_schemabody 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})data.deleteasks to confirm (--yes to skip)

tasks

CommandWhat it doesPermissionOptions
usertasks tasks listList tasks (GET /api/v1/tasks)tasks.view_all--status
--priority
--assignee-id
--is-workflow-task true / false
--parent-task-id
--strip-html true / false
--all --limit --offset
usertasks tasks assignedList open tasks assigned to a user or team (GET /api/v1/tasks/assigned)tasks.view_all--assignee-id
--team-id
--status
--acceptance-status
--strip-html true / false
--all --limit --offset
usertasks tasks get <id>Get a task (GET /api/v1/tasks/{id})tasks.view_all--strip-html true / false
usertasks tasks update <id>Update task fields and User Task field values (PATCH /api/v1/tasks/{id})tasks.completebody via -f / --set: title, description, status, priority, due_date, progress_pct, estimated_completion, tags, values
usertasks tasks action <id>Accept, hold, reject, complete, escalate or redirect a task (POST /api/v1/tasks/{id}/action)tasks.completebody via -f / --set: action*, outcome, outcome_notes, target_user_id, target_user_ids, target_email, target_emails, invite_if_needed, invite_role, comment, values
usertasks tasks ingestCreate a task (with optional subtasks) from an external system (POST /api/v1/tasks/ingest)tasks.createbody via -f / --set: title*, description, priority, due_date, assignee_email, estimated_effort, subtasks, workflow, idempotency_key

teams

CommandWhat it doesPermissionOptions
usertasks teams listList teams with member counts (GET /api/v1/teams)team.view_members
usertasks teams createCreate a team (POST /api/v1/teams)team.invitebody via -f / --set: name*, description, parent_id
usertasks teams get <id>Get a team with its members (GET /api/v1/teams/{id})team.view_members
usertasks teams update <id>Update a team (PATCH /api/v1/teams/{id})team.invitebody via -f / --set: name, description, parent_id
usertasks teams delete <id>Delete a team and its memberships (DELETE /api/v1/teams/{id})team.removeasks to confirm (--yes to skip)
usertasks teams add-member <id> <userId>Add a user to a team (idempotent) (PUT /api/v1/teams/{id}/members/{userId})team.invitebody via -f / --set: role
usertasks teams remove-member <id> <userId>Remove a user from a team (DELETE /api/v1/teams/{id}/members/{userId})team.removeasks to confirm (--yes to skip)

users

CommandWhat it doesPermissionOptions
usertasks users listList workspace users (GET /api/v1/users)team.view_members--search
--include-roles true / false
--include-teams true / false
--all --limit --offset
usertasks users add-role <id> <roleId>Give a user a role (idempotent) (PUT /api/v1/users/{id}/roles/{roleId})team.change_roles
usertasks users remove-role <id> <roleId>Remove a role from a user (DELETE /api/v1/users/{id}/roles/{roleId})team.change_rolesasks to confirm (--yes to skip)

webhooks

CommandWhat it doesPermissionOptions
usertasks webhooks list <id>List the inbound webhooks of a workflow (secrets are never returned) (GET /api/v1/workflows/{id}/webhooks)settings.manage_webhooks
usertasks webhooks create <id>Create an inbound webhook that triggers the workflow (POST /api/v1/workflows/{id}/webhooks)settings.manage_webhooksbody via -f / --set: slug, payload_mapping, is_active
usertasks webhooks get <id>Get a webhook (the secret is never returned) (GET /api/v1/webhooks/{id})settings.manage_webhooks
usertasks webhooks update <id>Update a webhook slug, payload mapping or active flag (PATCH /api/v1/webhooks/{id})settings.manage_webhooksbody via -f / --set: slug, payload_mapping, is_active
usertasks webhooks delete <id>Delete a webhook (DELETE /api/v1/webhooks/{id})settings.manage_webhooksasks to confirm (--yes to skip)
usertasks webhooks rotate <id>Replace a webhook secret (the old one stops working) (POST /api/v1/webhooks/{id}/rotate)settings.manage_webhooks

workflows

CommandWhat it doesPermissionOptions
usertasks workflows listList workflows (GET /api/v1/workflows)workflows.view--active true / false
--all --limit --offset
usertasks workflows createCreate a workflow from nodes and edges (POST /api/v1/workflows)workflows.editbody via -f / --set: name, trigger_type, nodes, edges, user_variables, description, trigger_config, swimlanes, sections, tags, is_active, publish, publish_notes
usertasks workflows get <id>Get a workflow with its recent runs (GET /api/v1/workflows/{id})workflows.view--run-id
--include-logs true / false
--include-definition true / false
usertasks workflows update <id>Save draft changes to a workflow (publish separately, or with publish: true) (PATCH /api/v1/workflows/{id})workflows.editbody via -f / --set: name, trigger_type, nodes, edges, user_variables, description, trigger_config, swimlanes, sections, tags, is_active, publish, publish_notes
usertasks workflows delete <id>Delete a workflow (queued: its versions, runs and spawned tasks go with it) (DELETE /api/v1/workflows/{id})workflows.deleteasks to confirm (--yes to skip)
usertasks workflows definition <id>Get the draft definition in author-payload shape (edit it and send it back to PATCH /workflows/{id}) (GET /api/v1/workflows/{id}/definition)workflows.view
usertasks workflows publish <id>Publish the draft as a new version (runs use it) and activate the workflow (POST /api/v1/workflows/{id}/publish)workflows.activatebody via -f / --set: notes
usertasks workflows startStart a workflow run (sync, or async via the queue) (POST /api/v1/workflows/start)workflows.activatebody via -f / --set: workflow_id*, variables, async, task_id, priority
usertasks workflows inputs <id>Get the input parameters a workflow run accepts (GET /api/v1/workflows/{id}/inputs)workflows.view
usertasks workflows activate <id>Activate a workflow (it responds to its trigger) (POST /api/v1/workflows/{id}/activate)workflows.activate
usertasks workflows deactivate <id>Deactivate a workflow (its trigger is paused) (POST /api/v1/workflows/{id}/deactivate)workflows.activate
usertasks workflows versions <id>List published versions of a workflow (newest first) (GET /api/v1/workflows/{id}/versions)workflows.view--all --limit --offset
usertasks workflows version <id> <versionId>Get one published version with its full definition (GET /api/v1/workflows/{id}/versions/{versionId})workflows.view
usertasks workflows instances <id>List live instances (waiting or paused runs) with their current node and version (GET /api/v1/workflows/{id}/instances)workflows.view_runs--status active / waiting_for_event / paused
--version-id
--all --limit --offset
usertasks workflows migrate-instances <id>Migrate live instances to another version (or dry-run the plan) (POST /api/v1/workflows/{id}/instances/migrate)workflows.manage_runsbody via -f / --set: to_version_id*, run_ids, from_version_id, all_active, node_map, default_target_node_id, dry_run

workspace-theme

CommandWhat it doesPermissionOptions
usertasks workspace-theme getGet the workspace theme (any member) (GET /api/v1/workspace-theme)any
usertasks workspace-theme updateReplace the workspace theme (PUT /api/v1/workspace-theme)settings.editbody via -f / --set: meta, colors, typography, shape, shadows, layout, chrome, branding, expected_version
usertasks workspace-theme apply-presetReplace the workspace theme with a built-in template (POST /api/v1/workspace-theme/apply-preset)settings.editbody via -f / --set: preset_id*, expected_version
usertasks workspace-theme presetsList the built-in theme templates (GET /api/v1/workspace-theme/presets)any
usertasks workspace-theme upload-fontUpload a woff2 font for the workspace theme (POST /api/v1/workspace-theme/fonts)settings.editbody via -f / --set: file_name, content_base64, family