CLI Reference

The tango-sdk CLI is included in tango-api and provides build, development, and validation tools.

Usage

The scaffolder sets up npm scripts that invoke the CLI:

{
  "scripts": {
    "dev": "bun node_modules/tango-api/src/cli.ts dev",
    "build": "bun node_modules/tango-api/src/cli.ts build",
    "sync": "bun node_modules/tango-api/src/cli.ts sync",
    "validate": "bun node_modules/tango-api/src/cli.ts validate",
    "publish": "bun node_modules/tango-api/src/cli.ts publish"
  }
}

If no project path argument is given, the current working directory is used.

---

Commands

build

Builds the instrument’s frontend and backend (if present) using Bun’s bundler.

tango-sdk build
# or
bun run build

What it does:

1. Reads the manifest from package.json
2. Builds src/index.tsx → dist/index.js (ESM, browser target)
3. If backendEntrypoint is set, builds src/backend.ts → dist/backend.js (ESM, bun target)

Output:

Build complete in 42ms — frontend: ok, backend: ok

Exit code: 1 if either build fails.

---

dev

Watches for changes and rebuilds automatically. Notifies the running Tango app to hot-reload.

tango-sdk dev
# or
bun run dev

What it does:

1. Syncs dependencies (clears Bun cache and runs bun install to refresh file: deps)
2. Runs an initial build
3. Watches src/ for file changes
4. Rebuilds on change
5. Sends a reload signal to the Tango dev server

Use this during development for the fastest feedback loop.

---

sync

Generates tango-env.d.ts with type declarations based on your instrument’s settings schema.

tango-sdk sync
# or
bun run sync

What it does:

1. Reads the settings array from your manifest
2. Generates a TypeScript declaration file with typed setting keys

Output:

Generated tango-env.d.ts

Run this after changing your settings schema to keep types in sync.

---

validate

Validates the instrument manifest and project structure.

tango-sdk validate
# or
bun run validate

Checks performed:

Check	Description
id	Present and is a string
name	Present and is a string
entrypoint	Present, is a string, and source file exists
panels	Present, at least one slot is true, no unknown slots, all booleans
permissions	If present, all values are valid permission strings
settings	If present, each has key, title, valid type; select type has options

Output on success:

Validation passed.

Output on failure:

Validation found 2 error(s):
  id: Missing or invalid 'id' (must be a string)
  panels: At least one panel slot must be true

Exit code: 1 if any errors found.

---

publish

Publishes your instrument to the official Tango marketplace by creating a pull request.

tango-sdk publish
# or
bun run publish

Prerequisites:

• GitHub CLI (gh) installed and authenticated (gh auth login)

What it does:

1. Validates your instrument manifest
2. Forks the central marketplace repo (MartinGonzalez/tango-instruments)
3. Copies your instrument source files into the fork
4. Updates the marketplace index (tango.json)
5. Creates a pull request for review

Excluded files (not copied to marketplace): node_modules/, .git/, dist/, .claude/, .env, .DS_Store, bun.lock, bun.lockb

Output:

[publish] Checking prerequisites...
[publish] Validating instrument...
[publish] Instrument: My Instrument (my-instrument)
[publish] Forking MartinGonzalez/tango-instruments...
[publish] Cloning fork...
[publish] Copying instrument files...
[publish] Pushing to fork...

[publish] PR created: https://github.com/MartinGonzalez/tango-instruments/pull/42

Updating an existing instrument: Run publish again — it force-pushes the branch and reports the existing PR URL.

---

Valid permissions

The validator accepts these 9 permission strings:

• storage.files
• storage.db
• storage.properties
• sessions
• connectors.read
• connectors.credentials.read
• connectors.connect
• stages.read
• stages.observe

Valid setting types

• string — text input (optional: default, placeholder)
• number — numeric input (optional: default, min, max, step)
• boolean — toggle (optional: default)
• select — dropdown (required: options array, optional: default)