deepflow-opendesk-cli

Python command-line client for OpenDesk admin configuration and outbound task APIs.

The CLI is designed for implementation engineers, operators, and AI agents that need to configure OpenDesk through the same APIs used by the admin console.

Scope

This package intentionally exposes admin configuration APIs and API-key outbound task management APIs. Runtime workspace data, public visitor APIs, reports, and call-center agent actions are excluded by a schema whitelist.

Included examples:

• System settings
• Roles, employees, employee groups
• Service hours
• Channels
• Field definitions, form layouts, interaction rules
• User, ticket, and organization view configuration
• Satisfaction and welcome-message settings
• Voice flows, ticket workflows, inbound/session routing rules
• Queue policies
• Outbound task templates, manual outbound tasks, and automatic outbound tasks
• Learning courses and exams (admin configuration)
• Optional tenant, SIP trunk, and phone-number configuration endpoints when extensions are loaded

Install For Development

cd packages/deepflow-opendesk-cli
pip install -e ".[dev]"

Configure Host And Token

export OPENDESK_HOST="http://localhost:5001"
export OPENDESK_TOKEN="..."

Or log in and save a local profile:

deepflow_opendesk_cli auth login \
  --tenant 12058577c8114513 \
  --username test \
  --save-token

Profile files are stored under ~/.opendesk/cli/{profile}/ with owner-only permissions where supported.

Common Commands

deepflow_opendesk_cli schema fetch
deepflow_opendesk_cli docs list --tag FieldDefinitions
deepflow_opendesk_cli docs show fields.create --json
deepflow_opendesk_cli docs schema FieldDefinitionCreate

deepflow_opendesk_cli request GET /api/v1/system/info
deepflow_opendesk_cli call fields.list --query domain=ticket
deepflow_opendesk_cli call fields.create --json-file field.json

deepflow_opendesk_cli system settings
deepflow_opendesk_cli roles permission-tree
deepflow_opendesk_cli employees list
deepflow_opendesk_cli channels list
deepflow_opendesk_cli call service_hours.list
deepflow_opendesk_cli call satisfaction.get
deepflow_opendesk_cli call welcome_rules.create --json-file welcome-rule.json
deepflow_opendesk_cli routing session list
deepflow_opendesk_cli queue policies
deepflow_opendesk_cli outbound-templates list
deepflow_opendesk_cli outbound-templates get-script 12
deepflow_opendesk_cli outbound-templates set-script 12 --json-file script.json
deepflow_opendesk_cli outbound-tasks list
deepflow_opendesk_cli auto-outbound-tasks list
deepflow_opendesk_cli call courses.list
deepflow_opendesk_cli call exams.list

Outbound Tasks

The outbound commands use the API-key OpenAPI under /api/v1/open/engagement. Set the tenant API key in OPENDESK_TOKEN or pass the global --token option before the command.

Manual task examples:

deepflow_opendesk_cli outbound-tasks create --json-file manual-task.json
deepflow_opendesk_cli outbound-tasks publish 18
deepflow_opendesk_cli outbound-tasks targets 18 --status pending
deepflow_opendesk_cli outbound-tasks add-target 18 \
  --json '{"phone_number":"13800138000","field_values":{"name":"Alice"}}'
deepflow_opendesk_cli outbound-tasks add-targets 18 --json-file targets.json
deepflow_opendesk_cli outbound-tasks import-targets 18 targets.xlsx
deepflow_opendesk_cli outbound-tasks records 18

Automatic task examples:

deepflow_opendesk_cli auto-outbound-tasks create --json-file auto-task.json
deepflow_opendesk_cli auto-outbound-tasks start 27
deepflow_opendesk_cli auto-outbound-tasks monitor 27
deepflow_opendesk_cli auto-outbound-tasks add-targets 27 --json-file targets.json
deepflow_opendesk_cli auto-outbound-tasks import-targets 27 targets.csv
deepflow_opendesk_cli auto-outbound-tasks mark-target-invalid 81
deepflow_opendesk_cli auto-outbound-tasks delete 27 --yes

add-targets accepts a JSON object containing 1–5000 targets:

{
  "targets": [
    {
      "phone_number": "13800138000",
      "user_id": 123,
      "field_values": {"name": "Alice", "customer_level": "VIP"}
    }
  ]
}

import-targets keeps the existing Excel/CSV file import behavior. Use docs show outbound_tasks.create or docs show auto_outbound_tasks.create after schema fetch to inspect the current request fields.

Equivalent module invocation:

python -m deepflow_opendesk_cli docs list

Construct Request Bodies

docs show <endpoint-key> expands the request body schema into a field tree (name, type, required, enum, description) and prints a generated example payload, so an agent can construct a valid body without reading the OpenAPI components by hand. docs schema <SchemaName> does the same for any component schema in the fetched OpenAPI document.

deepflow_opendesk_cli docs show fields.create
deepflow_opendesk_cli docs schema WelcomeMessageRuleCreate --json

Use the printed example as a starting point, edit values, then pass it with --json / --json-file. Add --dry-run to validate the plan without sending requests.

AI Agent Flow

Recommended execution loop:

1. schema fetch or docs list
2. docs show <endpoint-key> (and docs schema <SchemaName> for body details)
3. request/call --dry-run
4. present plan to a human
5. batch run / workflow run --yes
6. verify with config list/get commands

Batch

batch run accepts JSONL. Each line is a config operation:

{"key":"auth.me"}
{"key":"fields.create","body":{"domain":"ticket","name":"Customer Tier","field_type":"select"}}
{"method":"PUT","path":"/api/v1/system-settings","body":{"default_language":"zh","default_timezone":"Asia/Shanghai"}}

Run:

deepflow_opendesk_cli batch run ops.jsonl --dry-run
deepflow_opendesk_cli batch run ops.jsonl --continue-on-error --output results.jsonl

Workflows

workflow list shows named configuration workflows. Running a workflow without --json-file executes its built-in read-only plan, which snapshots the relevant current configuration (safe to run anytime). Pass --json-file with a batch-style operations array to run a custom write plan instead.

deepflow_opendesk_cli workflow list
deepflow_opendesk_cli workflow run setup-tenant --dry-run
deepflow_opendesk_cli workflow run setup-web-channel --json-file channel-plan.json --yes

Development

cd packages/deepflow-opendesk-cli
PYTHONPATH=src python -m pytest tests -q
python -m build

Distribution

Releases are automated. Pushing a v* git tag (e.g. v0.1.1) triggers .github/workflows/release.yml, which runs the tests, builds the sdist + wheel, publishes deepflow-opendesk-cli to PyPI, and cuts a GitHub Release.

pip install deepflow-opendesk-cli

To cut a patch release, run the helper script (bumps the version across pyproject.toml, setup.py, and __init__.py, then tags and pushes):

bash .claude/skills/release-publish/scripts/release-tag.sh --dry-run
bash .claude/skills/release-publish/scripts/release-tag.sh

To build locally without publishing: python -m build.