CLI, SDK and config

Config as code and GitHub sync

Export workspace configuration to files, review it in Git, diff and apply it across environments, or sync it with GitHub automatically.

Workflows, decision tables, custom steps, data-table schemas, integrations and references, objects, agents, reports, retention policies, roles, MCP servers, email templates, connectors, log destinations and the workspace theme can all be exported to files and applied to another workspace.

To ship a whole process — a workflow with everything it uses, signed and versioned, with the credentials each environment must supply asked for on install — build a package.

The folder layout

config/
├── manifest.json                      # index: asset type, id, name, file
├── workflows/invoice-approval-6f1c2a9b.json
├── decision-tables/invoice-approval-policy-1d0e4c77.json
├── integrations/northwind-erp-8a2b11c0.json
├── references/get-vendor-03c9d1aa.json
├── email-templates/invoice-approved-5b7e9f12.json
├── log-destinations/splunk-production-2c4d6e8f.json
├── workspace-theme.json               # the one workspace theme (no id)
└── …

The same layout is used by the CLI, the /api/v1/config/export and /api/v1/config/apply endpoints and GitHub sync. Files are JSON or YAML.

Rules

• Secrets are always exported as __SECRET__. Put ${env:VAR} or ${file:path} in their place; the CLI substitutes them locally before upload. Sending __SECRET__ keeps the stored value.
• Apply never deletes. Running the same apply twice reports everything unchanged.
• Identity — assets keep stable ids. Ids are mapped per --source-label (use one label per source workspace); --adopt-by-name links unmapped assets to existing ones with the same unique name.
• Workspace theme — workspace-theme.json replaces the target's theme (needs settings.edit). Uploaded fonts are matched by file name in the target workspace; logos from another workspace are dropped, with a warning. GitHub sync does not carry the theme.
• Dependencies — references between assets (a workflow's decision table, reference or agent) are rewritten to the target workspace's ids.

usertasks config new workflow "Vendor onboarding" --dir ./config   # scaffold a file with a fresh id
usertasks config diff ./config --exit-code                          # exit 7 when apply would change something
usertasks config apply ./config --dry-run

See the CLI recipes for a full dev → prod flow and a CI example.

Export and import

Every list of artifacts in the app has an Import button, and each row or detail header has an Export button. This covers workflows, decision tables, custom steps, data tables, integrations, connectors, email templates, reports, agents, retention policies, custom roles, MCP servers and log destinations.

• Export downloads <name>.usertasks.json, a one-file config manifest. Include dependencies adds everything the asset uses: sub-workflows, activities, rules, data tables, integrations and connectors, email templates, agents and custom roles. For data tables, Include table rows adds up to 10,000 rows per table.
• Import accepts that file, a config folder's files, a single asset file or a per-type export (decision table, report, activity or agent designer file). It shows the dry-run plan first and then applies it. You choose how rows are written: merge, replace or skip.

The same export and import works on every other surface:

usertasks config export ./out --ids <workflow-id> --with-dependencies     # one asset and what it needs
usertasks config export ./out --ids <table-id> --include-rows             # a data table with its rows
usertasks config apply ./out --dry-run && usertasks config apply ./out --rows-mode merge

• REST: GET /api/v1/config/export?ids=…&with_dependencies=true&include_rows=true and POST /api/v1/config/apply (with rows_mode).
• MCP: config_export (ids, with_dependencies, include_rows) and config_apply (dry_run, rows_mode).

API keys, OAuth apps, webhooks, people and runtime data are never exported. Export and import coverage lists every artifact type by surface, what is left out on purpose and why.

GitHub sync

Settings → GitHub Sync connects one repository (branch, path prefix, a token that can write) and keeps the workspace configuration there:

• Push — changes are queued and committed (manually, or automatically every minute), or run a full or scoped sync on demand.
• Schedule — hourly, daily or weekly full syncs in your time zone.
• Deploy — import a branch, ref or pinned commit into the workspace, with a dry run first.

usertasks github-sync status
usertasks github-sync sync                     # full resync (or --set kind=commit for pending changes)
usertasks github-sync runs
usertasks github-sync deploy --set ref=main --set dry_run:=true
usertasks github-sync deployments

Every sync and deployment runs in the background and returns an id to poll; results appear as system.sync.github.* events. Permissions: sync.view, sync.manage, sync.deploy.