CLI, SDK and config

CLI recipes

Edit a workflow, promote configuration from dev to prod, gate CI on drift, monitor logs and ship them.

Edit a workflow from your editor

bash

usertasks workflows definition <id> -o json > wf.json
# edit wf.json: add a node to "nodes" and an edge to "edges", change variables…
usertasks workflows update <id> -f wf.json          # saves the draft; changed: false if nothing differs
usertasks workflows publish <id> --set notes="Add CFO approval over 50k"
usertasks workflows versions <id>

Runs keep using the previous version until you publish.

Terminal: workflow edit round trip — Export the draft, edit, update and publish.

Promote configuration from dev to prod

bash

usertasks --profile dev config export ./config --format yaml
git add config && git commit -m "Invoice approval v2"
usertasks --profile prod config diff ./config --source-label dev
usertasks --profile prod config apply ./config --source-label dev
usertasks --profile prod config apply ./config --source-label dev   # again: everything unchanged

Secrets are exported as __SECRET__. Replace them with ${env:VAR} or ${file:path}; the CLI substitutes them on your machine before upload. Apply never deletes. Use one --source-label per source workspace so ids map correctly.

Terminal: config export and diff — `config diff` shows exactly what an apply would create or update.

Gate CI on drift

.github/workflows/usertasks.yml

name: usertasks config
on:
  pull_request:
  push:
    branches: [main]
jobs:
  config:
    runs-on: ubuntu-latest
    env:
      USERTASKS_URL: ${{ secrets.USERTASKS_URL }}
      USERTASKS_API_KEY: ${{ secrets.USERTASKS_API_KEY }}
      ERP_TOKEN: ${{ secrets.ERP_TOKEN }}
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: 20 }
      - run: npm install -g @usertasks/cli
      - run: usertasks config diff ./config --source-label dev --exit-code   # exit 7 = changes
        if: github.event_name == 'pull_request'
        continue-on-error: true
      - run: usertasks config apply ./config --source-label dev
        if: github.ref == 'refs/heads/main'

Watch production

bash

usertasks logs tail --severity error                       # everything that fails
usertasks logs tail --type 'workflow.run.*' --workflow <id>  # one workflow's runs
usertasks logs tail -o json | jq 'select(.type == "integration.call") | .attributes.status'
usertasks logs export --since 24h --category audit,security > audit.ndjson

Ship logs to Splunk

splunk.json

{
  "name": "Splunk production",
  "type": "splunk_hec",
  "config": { "url": "https://splunk.example.com:8088", "index": "usertasks" },
  "credentials": { "token": "${env:SPLUNK_HEC_TOKEN}" },
  "filters": { "categories": ["workflow", "integration"], "min_severity": "info" }
}

bash

usertasks log-destinations create -f splunk.json
usertasks log-destinations test <id>
usertasks log-destinations status <id>

Terminal: creating a Splunk destination and checking its status — Create a destination from a file, then check delivery and lag.

Bulk operations with jq

bash

# complete every low-priority task assigned to me
usertasks tasks assigned --all -o json | jq -r '.[] | select(.priority == "low") | .id' |
  xargs -I{} usertasks tasks complete {} --outcome Approved --notes "Bulk approved"