TON Builders Portal CLI

Package @ton/cli-developer-portal · binary tdp. Built for terminal-class AI agents (Claude Code, Codex, OpenCode) and CI pipelines. Complementary to the hosted MCP server — different audience, different transport.

The CLI is spec-driven: every curated command (projects list, projects get, …) is described by a JSON document. The npm package does not bundle that document — tdp spec refresh fetches it at first run from our backend at https://builders-backend.ton.org/cli-spec.json (primary), with a GitHub-raw copy at the root of this repo as fallback. Updates ship the moment a backend deploy lands; no CLI release required for a new curated command.

For AI agents

Want an agent (Claude Code, Codex, Cursor, OpenCode, …) to use tdp on your behalf? Paste this URL into your agent and ask it to follow the instructions there:

https://raw.githubusercontent.com/ton-org/cli-developer-portal/main/AGENTS.md

Or open AGENTS.md in this repo, copy the content, and paste it directly into the chat. The file is short and self-contained — your agent will install the CLI, fetch the command surface, and be ready to act on your task without you writing a setup prompt.

Prerequisites

• Node.js >= 18

Install

Package: @ton/cli-developer-portal on npm. Binary: tdp.

# globally (recommended for interactive use)
npm i -g @ton/cli-developer-portal
tdp --help

# one-shot (no install)
npx -y @ton/cli-developer-portal --help

Local dev

git clone <repo-url> tdp && cd tdp
npm install
npm run build       # bundles src/ into dist/index.js (~180 KB ESM)

Run the bundled bin directly (shebang + chmod set by the build):

./dist/index.js --help

Or symlink into a user-writable PATH directory:

ln -sf "$(pwd)/dist/index.js" ~/.local/bin/tdp
tdp --help

npm link typically fails on macOS Homebrew/system Node because /usr/local/lib/node_modules requires root. The symlink approach avoids that.

First-run flow

# 1. fetch the curated command surface
tdp spec refresh        # primary: our backend ${TDP_API_URL}/cli-spec.json
                           # fallback: this repo on GitHub raw

# 2. authenticate
tdp login

# 3. issue curated commands
tdp projects list
tdp projects get <id>

Step 1 is mandatory — until the cache is populated only the static commands (login / logout / whoami / manifest / spec) are wired. tdp spec show reports status: uncached in that state and points at both URLs.

Commands

Static (always present)

| Command | What it does | |---|---| | tdp login | Run OAuth 2.1 Device Flow against the configured issuer; cache tokens at ~/.config/tdp/credentials-<issuer-slug>.json (mode 0600). | | tdp logout | Delete the cached credentials. | | tdp whoami | Read cached tokens locally; print status, scope, expiry, refresh metadata, token file. Does not contact the server. Cheap auth-state probe. Exits 2 if not signed in. | | tdp manifest | Print the full CLI manifest as JSON: setup, envelopes, exit codes, env vars, commands. Read once by an agent. | | tdp spec refresh | Fetch the CLI spec from the configured URL and cache it locally. | | tdp spec show | Print metadata about the cached spec (no network call). |

Spec-driven (curated, defined by the backend's cli-spec.json)

| Command | Source | |---|---| | tdp projects list | Bound to GET /api/v1/me/projects. Renders as a Unicode-bordered table. | | tdp projects get <id> | Bound to GET /api/v1/projects/{projectId}. Renders as a detail view. |

Adding more commands is a backend-side operation: edit cli-spec.json, redeploy backend, users refresh.

Configuration

Defaults target the testing environment. Override any axis via env vars:

| Env var | Default | Purpose | |---|---|---| | TDP_API_URL | https://builders-backend.ton.org | REST API base URL. Also the default OAuth issuer and CLI-spec source. Transitional (2026-05): production backend at this host doesn't yet expose every endpoint tdp uses (OAuth Device Flow, /me/projects, faucet, …). Until production catches up, set TDP_API_URL=https://testing-builders-backend.dev-internal.org to hit the testing environment that has the full surface. | | TDP_OAUTH_ISSUER | value of TDP_API_URL | OAuth issuer base URL. Set only when issuer is hosted separately from REST API. Determines the credentials-file slug. | | TDP_OAUTH_CLIENT_ID | ton-developer-platform | OAuth client id. | | TDP_TOKEN_FILE_PATH | ~/.config/tdp/credentials-<issuer-slug>.json | Token cache location. Per-issuer namespacing keeps environments independent; explicit value bypasses namespacing. | | TDP_CLI_SPEC_URL | https://builders-backend.ton.org/cli-spec.json | Primary URL fetched by tdp spec refresh. Full URL to the spec JSON including the filename — fetched verbatim. Defaults to the production Builders Portal backend; override to point at a local or testing backend (e.g. http://localhost:8080/cli-spec.json). | | TDP_CLI_SPEC_FALLBACK_URL | https://raw.githubusercontent.com/ton-org/cli-developer-portal/main/cli-spec.json | Fallback URL tried only when the primary fails (network error, non-2xx). Defaults to the GitHub-raw view of cli-spec.json at the root of this repo — keeps the CLI bootable when the backend is briefly unreachable. Set to an empty string to disable the fallback entirely. | | TDP_NO_BROWSER | unset | Skip browser auto-open during login. | | TDP_OUTPUT | pretty | pretty or compact. Compact emits single-line JSON envelopes (agent-friendly). | | TDP_TABLE_STYLE | unicode | unicode or ascii — box-drawing style for table output. | | NO_COLOR / FORCE_COLOR | unset | De-facto standards for disabling/forcing ANSI colour output. |

Output contract

All data-returning commands wrap their payload in a JSON envelope:

{
  "data": <command-specific>,
  "hints": [{ "command": "...", "when": "..." }]
}

Errors mirror the envelope on stderr:

{
  "error": "...",
  "code": "not_authenticated | not_found | api_error | network_error | unknown",
  "status": 404,
  "body": {...},
  "hints": [...]
}

Exit codes:

| Code | Meaning | |---|---| | 0 | success | | 2 | not authenticated (401/403 or no creds) — run tdp login | | 3 | not found (404) | | 4 | API error (other 4xx/5xx) | | 5 | network or unknown error |

For human use, the default rendering is pretty JSON (or a Unicode table/detail view when the command declares it). For agents, set TDP_OUTPUT=compact or pass --compact per call. Run tdp manifest --compact to discover the full surface (envelope shape, exit codes, env vars, per-command schemas) in a single call.

Scripts

| Script | Purpose | |---|---| | npm run build | esbuild bundle src/index.ts → dist/index.js | | npm run typecheck | tsc --noEmit | | npm run dev | Build then run | | npm start | Run the bundled dist/index.js |

Layout

tdp/
├── package.json
├── tsconfig.json
├── esbuild.config.mjs
├── README.md
├── AGENTS.md               agent-onboarding guide — pasted into agents to install + orient them in one read
├── LICENSE
├── cli-spec.json           public mirror of the backend spec — served via GitHub raw as the CLI's fallback URL
├── src/
│   ├── index.ts            citty entry + subcommand wiring
│   ├── manifest.ts         agent-facing manifest (for_agents, commands, …)
│   ├── config.ts           env-resolved runtime configuration
│   ├── auth.ts             OAuth Device Flow + filesystem token store + refresh metadata
│   ├── api.ts              apiGet + ApiError + handleApiError (401-retry, exit codes)
│   ├── output.ts           writeResponse / writeTable / writeDetail / writeError + ANSI palette
│   ├── commands/spec.ts    `tdp spec refresh | show`
│   └── spec/
│       ├── types.ts        CommandSpec / CliSpec types
│       ├── fetch.ts        fetch + filesystem cache (per-issuer slug)
│       ├── builder.ts      CommandSpec[] → citty command tree
│       └── formatters.ts   named formatters referenced by JSON spec
└── dist/                   (gitignored) bundled output

cli-spec.json at the root is NOT bundled into the npm package (package.json#files only lists dist/, README.md, LICENSE). It lives in git so that https://raw.githubusercontent.com/ton-org/cli-developer-portal/main/cli-spec.json serves the file directly — that's what TDP_CLI_SPEC_FALLBACK_URL targets.

Source of the curated spec

By default the spec is served from our own backend — the TON Builders Portal at https://builders-backend.ton.org/cli-spec.json. That's the fastest path and is the primary TDP_CLI_SPEC_URL target. The same cli-spec.json is mirrored at the root of this repo and exposed via GitHub raw as the fallback, so the CLI stays bootable for first-time users and CI when the backend is briefly unreachable.

Updates to the curated command set ship through the backend — no CLI release required.

Formatter changes (src/spec/formatters.ts) still need an npm publish; everything else flows through the spec.