deepflow-opendesk-cli

Python command-line client for OpenDesk admin configuration 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 only admin configuration 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 and outbound scripts
• 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 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 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

Equivalent module invocation:

python -m deepflow_opendesk_cli docs list

AI Agent Flow

Recommended execution loop:

1. schema fetch or docs list
2. docs show <endpoint-key>
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

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.