coding-cli

Agent-first CLI + Claude Code skill for operating a self-hosted CODING instance over its OpenAPI surface (429 actions, 17 categories). Built as a generic spec-driven passthrough: one coding call <Action> invokes any action, backed by a bundled action index for discovery, validation, and safety.

• Base URL: your CODING instance's OpenAPI endpoint, e.g. https://<your-coding-host>/open-api — set it via --base-url / CODING_API_BASE / config init (the built-in default is a coding.example.com placeholder)
• Auth: personal access token (Authorization: token <…>)

Install (dev)

npm install
npm run regen      # tsc + build the action index/docs from the spec
npm link           # expose the `coding` binary on PATH (optional)

Quick start

coding config init --base-url https://<your-coding-host>/open-api   # writes ~/.coding/config.json
coding auth login                               # hidden token prompt (or: coding auth login --token -)
coding auth status --json                       # verify -> current user

coding actions --search issue --json            # discover actions
coding schema CreateIssue --json                # params / response / errors / risk
coding call DescribeProjectIssueList \
  --param ProjectName=demo --select 'Data.List[].Code,Data.List[].Name' --limit 20 --json

CODING_TOKEN / CODING_API_BASE / CODING_PROFILE env vars override config.

Output contract

Pass --json for the envelope:

{ "ok": true,  "action": "DescribeTeam", "requestId": "…", "data": { /* Response minus RequestId */ } }
{ "ok": false, "action": "…", "requestId": "…", "error": { "code|type": "…", "message": "…", "hint": "…" } }

Exit codes: 0 ok · 2 usage · 3 auth · 4 not-found · 5 remote/network · 6/7 config · 8 forbidden/scope · 9 rate-limit · 10 confirmation-required · 11 validation.

Safety

Destructive actions (Delete*, Remove*, Disable*, …) are gated: calling one without --yes exits 10 with a confirmation_required envelope. Preview any request with --dry-run (redacts the token, never sends, never trips the gate). Validation rejects unknown action / missing-required / unknown-param by default; --force (--no-validate) bypasses it for actions your instance has that the public spec lacks.

The skill

skills/coding/SKILL.md teaches an agent the bootstrap, discovery, call recipe, output/exit-code contract, error/scope playbook, and the exit-10 protocol. Curated per-domain playbooks (issues, code/MRs, CI, CD, artifacts, project, test, permissions, org, wiki, service hooks, programs, files, export, admin) live in skills/coding/references/ and load on demand — SKILL.md §9 is the router. Keeping them as reference files (rather than separate skills) means only one skill description sits in the agent's context, so the playbooks add no always-on token cost.

Regenerating the spec artifacts

generate_docs.py (the original Python doc generator) is superseded by src/core/specBuild.ts, which emits both generated/index.json and the docs/*.md reference from one parse. Two ways to run it:

npm run regen          # dev: tsc + build from spec/coding-openapi.yaml (cache-first), else fetch
coding update          # refresh from the LIVE spec, persist the cache, report an added/removed diff
coding update --offline   # rebuild from the cached spec only (no network)
coding update --dry-run   # report what would change without writing

coding update fetches the latest spec, then atomically swaps in the rebuilt docs/ (pruning stale files) and generated/index.json. Distribution is local/dev for now, so CLI/skill code upgrades happen via git pull + npm run regen; update keeps the spec artifacts current.

Offline / air-gapped install

To install on a server with no registry access, build a self-contained tarball with pnpm pack:offline and npm install -g --offline it on the target host. See Offline / air-gapped install in the root README.