cli

Taufinity CLI

Command-line tool for the Taufinity content platform. Manage templates, trigger playbooks, and configure Claude Code / Claude Desktop MCP integration.

Installation

macOS / Linux (Go 1.21+)

go install github.com/taufinity/cli/cmd/taufinity@latest

The binary is installed as taufinity in $GOPATH/bin (usually ~/go/bin). Make sure that directory is in your $PATH:

echo 'export PATH="$HOME/go/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc

Verify installation

taufinity version

Update

Use the built-in update command:

taufinity update           # install latest, with backup + smoke test
taufinity update --check   # report current vs latest, no install
taufinity update --rollback  # restore the previous binary

taufinity update backs up the running binary to <path>.prev before installing (when the install target is the same directory as the running binary), runs go install github.com/taufinity/cli/cmd/taufinity@latest, then smoke-tests the new binary. If the smoke test fails, the previous binary is restored automatically. Use --rollback if a working but unwanted version slipped in.

Staleness warning

On every invocation, taufinity makes a background call to GitHub (cached for 24h) and prints a one-line stderr warning when a newer commit is available on main. The check never blocks the command. Suppress it with:

TAUFINITY_NO_UPDATE_CHECK=1 taufinity ...       # one-off
taufinity config set update_check false         # permanent

Security note

taufinity update installs from the main branch via go install ...@latest. Anyone with commit access to main ships to all CLI users on their next update. Acceptable for the small internal team today; once we cut tagged releases, the default will move to a tagged version.

Build from source

git clone https://github.com/taufinity/cli.git
cd cli
make install    # installs to ~/bin/taufinity

To update: git pull && make install.

Authentication

taufinity auth login

Opens a browser window for device authorization. Credentials are stored at ~/.config/taufinity/credentials.json.

Quick Start

# 1. Authenticate
taufinity auth login

# 2. Preview a template locally
taufinity template preview

# 3. Trigger a playbook
taufinity playbook trigger <playbook-id>

Commands

Claude Desktop one-command install

After taufinity auth login:

taufinity mcp install

Writes a server entry to Claude Desktop's config (~/Library/Application Support/Claude/claude_desktop_config.json on macOS, %APPDATA%\Claude\claude_desktop_config.json on Windows). Restart Claude Desktop to load it.

Note: mcp install bakes the current bearer token into the config. When your session expires, Claude Desktop will silently start returning auth errors. Re-run taufinity mcp install --force to refresh it, or use the stdio bridge below which refreshes tokens automatically.

For Claude Code (.mcp.json), use taufinity mcp login instead.

Run any command with --help for full flag documentation.

MCP stdio bridge

For automatic token refresh and multi-org setups, use taufinity mcp stdio. It forwards JSON-RPC from Claude Desktop over stdio to Studio's /mcp endpoint, reloading credentials from disk on every request.

Example Claude Desktop config:

{
  "mcpServers": {
    "taufinity-studio": {
      "command": "taufinity",
      "args": ["mcp", "stdio"]
    }
  }
}

Pinning a specific organization — if your global CLI config points to a different org than the MCP server should use, pass --org with the organization ID:

{
  "mcpServers": {
    "taufinity-acme": {
      "command": "taufinity",
      "args": ["--org", "3", "mcp", "stdio"]
    }
  }
}

This sends X-Organization-ID: 3 on every request, overriding the org embedded in the JWT.

Flags:

• --org ID — pin to a specific organization (overrides JWT org).
• --api-url URL — override the upstream (defaults to $TAUFINITY_API_URL, then config, then https://studio.taufinity.io).
• --timeout DURATION — per-request timeout (default 5m, accommodates BigQuery-backed tools).

Configuration

Config is resolved in this order (highest priority first):

Environment Variables

Project File (taufinity.yaml)

site: mysite_com
template: templates/article.html
preview_data: fixtures/article.json
ignore:
  - node_modules/
  - dist/

License

Apache License 2.0 — see LICENSE.