Download all docs

The Triform CLI

The Triform CLI is the fastest way to drive your platform from a terminal. The classic platform client is triform, with triform-cli kept as a compatibility alias. The installer also provides the local triton agent (triton2 is its temporary compatibility alias) and a MCP server (triform-mcp).

One install gives you all of it: a chat agent, a uniform command for every element operation, and the MCP bridge your editor’s agent can call.

Quickstart

Three commands take you from nothing to a live call:

# 1. Install (auto-detects your OS + architecture)
curl -fsSL https://triform.cloud/downloads/install.sh | sh

# 2. Authenticate (opens your browser; or use a token — see Authenticate)
triform auth login

# 3. List the tools available in your circle
triform tools

If triform isn’t found after step 1, add the install dir to your PATH (the installer prints the exact line) and re-open your shell:

export PATH="$HOME/.triform/bin:$PATH"

Install

The installer detects your OS/arch, downloads the matching prebuilt binary, verifies each SHA-256 checksum, and installs triform, triform-cli, triform-mcp, triton, and triton2 into ~/.triform/bin. The platform CLI and local agent have independent release channels and cannot update over one another. Prebuilt binaries are published for Linux (x86_64, arm64), macOS (Apple Silicon + Intel), and Windows (x86_64).

Linux & macOS:

curl -fsSL https://triform.cloud/downloads/install.sh | sh

Windows (PowerShell):

irm https://triform.cloud/downloads/install.ps1 | iex

Options (set as environment variables before the command):

  • TRIFORM_VERSION=0.1.2 — pin a specific version instead of the latest.
  • TRITON_VERSION=0.2.0 — independently pin the local agent version.
  • TRIFORM_BIN_DIR=/usr/local/bin — install somewhere other than ~/.triform/bin.

Verify

triform --version          # prints the version + build SHA
triform --help             # full command reference
triton --version           # local-agent version
triton --help              # local-agent command reference

Troubleshooting

  • triform: command not found — the install dir isn’t on your PATH. Add export PATH="$HOME/.triform/bin:$PATH" to your shell rc (~/.zshrc, ~/.bashrc) and re-open the terminal.

  • macOS “cannot be opened because the developer cannot be verified” — the installer already strips the Gatekeeper quarantine flag; if you moved the binary by hand, run xattr -dr com.apple.quarantine ~/.triform/bin/triform.

  • macOS binary not found right after a brand-new release — Mac builds are added natively shortly after each release, so a just-cut version may briefly lag. Retry in a moment, pin an older version with TRIFORM_VERSION=…, or build from source (no SDK needed beyond the Xcode Command Line Tools):

    cargo build --release -p triform-cli -p triform-mcp
# then copy target/release/{triform,triform-mcp} onto your PATH
# build the local agent separately from the triton/ workspace

Authenticate

Triform talks to a circle on your behalf. Authenticate once and it remembers:

triform auth login            # interactive browser login
triform auth login --no-browser   # print a URL to open elsewhere (headless / SSH)
triform auth set-api-key <trif_…> # use a bearer token instead of a browser
triform auth status           # show who you're authenticated as
triform auth logout           # clear stored credentials

For production (triform.cloud) and CI, don’t use a browser login — mint a trif_ token from an api-token element in your circle and pass it to triform auth set-api-key, or set it inline with TRIFORM_API_KEY. See Authentication & access.

Point the CLI at a target and circle (persisted in your config):

triform config show               # the resolved circle + URLs
triform config set-circle <name>  # default circle for commands
triform config set-url <url>      # API target, e.g. https://triform.cloud

You can also override per-command with --circle, --api-url, and --api-key (or the matching TRIFORM_CIRCLE / TRIFORM_API_URL / TRIFORM_API_KEY environment variables).

Platform chat

The classic CLI retains its server-backed chat path for compatibility:

triform                       # open chat; prompts for login when needed
triform "your prompt"         # open chat with an initial prompt
triform -p "your prompt"      # print one response and exit (scriptable)
triform -p --raw "prompt"     # print only the response body and exit
triform -c                    # continue the latest chat in this directory
triform -r <conversation>     # resume a specific chat by name or id

Work locally with Triton

Triton runs its agentic loop on your machine, executes tools in the current working directory, and sends model traffic only through the Triform platform gateway:

triton                              # interactive local agent
triton "summarize this repository"  # start with a prompt
triton prompt "fix the failing test" # one non-interactive turn
triton circle status                # circle-aware git porcelain
triton update --check               # check only the triton-v* channel

Authenticate once with triform auth login; Triton reuses the same platform session and never asks for a vendor API key.

Manage elements

Slug-addressed shorthands cover the element lifecycle without remembering URLs:

triform create <slug> --type <T> --name <N> [--description <D>] [--circle <C>]
triform get <slug>                # fetch an element (with its _actions/_lifecycle)
triform delete <slug> --confirm
triform enable <slug>
triform disable <slug>

Call any element operation

Every element operation is reachable as a uniform CLI command — the same shape for a python function, an sql query, or a slack message:

triform tools                          # list the tools available in your circle
triform <tool> <action> [--field value ...]
triform <tool> --action <action> [--field value ...]
triform <tool> --input '{"field":"value"}'
triform <tool> --help                  # schema + actions for one tool

Slug-addressed fields (like --slug) resolve against your default circle, so set one first with triton config set-circle (or pass --circle / TRIFORM_CIRCLE per-command, as shown above) — without it you’ll see a Missing path param: element_path error.

Control the output format with -o json|yaml|table (default table).

The tool catalog the CLI scripts, the MCP server exposes to agents, and the HTTP API serves are the same surface — a workflow you script one way is callable verbatim the others.

Wire it into your coding agent (MCP)

The installer also drops triform-mcp. Point any MCP-capable agent at it and it gains the same tool catalog. For example, with Claude Code:

claude mcp add triform \
  --env TRIFORM_API_URL=https://triform.cloud \
  --env TRIFORM_API_KEY=trif_your_token \
  -- "$HOME/.triform/bin/triform-mcp"

See the MCP server guide for other clients and the full tool surface.

Prefer your own editor + Claude Code?

The CLI isn’t the only way in. Your circle is a real git repo — you can git clone it and run Claude Code (or any agent) directly against a normal checkout, no MCP bridge required. See Clone your circle + run Claude Code.

Related

Command reference

A complete index of every verb the triton and triform CLIs accept at top level. Each entry shows the literal spelling, the most useful flags, and the help string the CLI itself prints. If triton --help and this page ever disagree, this page is wrong — open an IMPROVE.

Platform verbs

auth

triform auth <login|set-api-key|status|logout>

The CLI’s own help output (from triform auth --help):

Usage:
  triform auth register
  triform auth register --username <name> --password <pw> --email <addr>
  triform auth login
  triform auth login --circle <circle>
  triform auth login --no-browser
  triform auth login --clone [--dir <path>]   # clone the circle after login
  triform auth login --no-clone               # skip the clone offer
  triform auth login --dev-circle <circle>
  triform auth passwd  # change your password (prompts)
  triform auth passwd --current <pw> --new <pw>
  triform auth set-api-key <token>
  triform auth status
  triform auth logout
  triform auth ...  # compatibility alias

config

triform config <set-circle|set-url|set-chat-url|show>

The CLI’s own help output (from triform config --help):

Usage: triform config <set-circle NAME|set-repo-path PATH|set-url URL|set-chat-url URL|show>

tools

triform tools

List the tools available in your circle. Output format follows -o json|yaml|table (default table).

chat

A bare triform with no subcommand opens chat; the CLI itself prints the canonical spellings:

triform                          Open Triform chat; prompts for login when needed
triform "prompt"                 Open Triform chat with an initial prompt
triform -p "prompt"              Print one Triform response and exit
triform -p --raw "prompt"        Print only the response body and exit
triform -c                       Continue the latest Triform chat
triform -r <conversation>         Resume a Triform chat

help

triform help

Prints the same help as triform --help (the clap-rendered usage block plus the TOOL_HELP after-block).

update

triform update [--check]

Self-update to the latest released CLI. --check reports whether a newer release is available without swapping the binary.

crew

The CLI’s own help output (from triform crew --help):

triform crew — orchestrate a crew of triformer agents

Usage:
  triform crew list                          List triformers in the circle
  triform crew delegate --to <slug> "<prompt>" [--wait] [--workspace <path>]
                                            Delegate a task to one agent
  triform crew status <delegation_id>        Check a delegation's status/result
  triform crew cancel <delegation_id> [--reason "..."]
                                            Cancel a running delegation
  triform crew sessions                      List recent agent sessions
  triform crew signals [--limit N] [--type <event_type>]
                                            List agent tool-level signals
  triform crew health                        Agent health summary (success rate, tool calls)
  triform crew orchestrate <plan-file>       Fan out a plan of delegations and
                                            wait for all to finish

Plan file (JSON or YAML) for `orchestrate`:
  { "tasks": [ { "to": "ada", "prompt": "..." },
               { "to": "helm", "prompt": "..." } ] }

Flags:
  --to <slug>        Target agent slug (delegate)
  --wait             Poll until the delegation reaches a terminal state
  --workspace <p>    Workspace path to focus the delegate on (repeatable)
  --reason "<text>"  Cancellation reason (cancel)
  --limit N          Max signals to return (signals; default 50)
  --type <t>         Filter signals by event_type (e.g. agent.tool.failed)

The circle is taken from --circle, $TRIFORM_CIRCLE, or `triform config set-circle`.

init

triform init [--reauth]

triform init — set up a local workspace for your circle

  triform init [--reauth]

Logs you in (if needed), mints a git access token for your circle, clones the
circle's repo (draft branch) into a folder you choose, and remembers it so
`triform sync` can keep it live.

  --reauth   force minting a fresh git token even if one is already stored

After init:
  triform push   publish local edits to the draft branch
  triform sync   continuously pull draft changes into your local folder

sync

triform sync [--once] [--interval <seconds>]

  --once             pull a single time and exit
  --interval <secs>  poll interval (default 15)

clone, push, build, promote, status, deploy

The git-native deploy group. The CLI’s own help output (from triform clone --help and the matching verbs):

triform git-native deploy commands

  triform clone <circle> [--dir <path>] [--no-recurse]
      Recursively clone a whole circle (every element as a submodule) at the
      draft branch, then pull each element's latest draft tip.

  triform push [--element <path>]
      git push HEAD:draft for the element repo in the current directory
      (advances source + reconciles spec; does NOT build/deploy).

  triform build [--element <path>] [--clean]
      POST ops/build — the deploy step for an SPA (serve reads builds/latest).

  triform promote <demo|live> [--element <path>]
      POST ops/source/promote — the release (draft->demo->live ref move).

  triform deploy [--element <path>] [--clean] [--promote <demo|live>]
      push HEAD:draft -> build -> optional promote, in order.

  triform status [--element <path>]
      Show source/status (branches, clone URL) for the element repo.

Auth: uses the resolved token (see `triform auth`). For git against another
circle, that token must be scoped to it — generate a trif_ token from an
api-token element in the circle (a personal login token is refused by git).

--element defaults to "<circle>" for clone, else is inferred from the element
repo's remote. <circle> for clone is taken from the arg or --circle/TRIFORM_CIRCLE.

Element shorthand verbs

These verbs are slug-addressed shorthands that translate to a real triform <tool> <action> call. The positional <slug>, when bare (single segment), is resolved under the current circle (--circle / TRIFORM_CIRCLE); for a nested element, give the full circle-rooted ancestry — e.g. triform get my-circle/my-lab/my-eyes — the CLI does not compose parent segments.

create

triform create <slug> --type T --name N [--description D] [--circle C]

--type is accepted as an alias for --element-type (the canonical element-tool flag). All other arguments below are forwarded to the element tool unchanged.

--element-path is the PARENT path and must itself be a full circle-rooted path (e.g. my-circle/my-parent), not a bare parent slug. Parent segments are never composed from --slug — give the whole ancestry explicitly. IMPROVE-5001.

get

triform get <slug>

Fetch an element (with its _actions / _lifecycle attachment).

delete

triform delete <slug> --confirm

--confirm is required; the CLI will refuse without it.

disable

triform disable <slug>

Suspend element execution. Reads still succeed; ops are rejected.

enable

triform enable <slug>

Resume element execution.

Generated tool commands

Every element operation is reachable as a uniform CLI command. The CLI itself documents the four invocation patterns:

Generated tool commands:
  triform <tool> <action> [--field value ...]
  triform <tool> --action <action> [--field value ...]
  triform <tool> --input '{"field":"value"}'   (aliases: --json, --patch)
  triform <tool> --help

Run triform tools to list the tools available in your circle, and triform <tool> --help to see a specific tool’s schema + actions.

The tool catalog the CLI scripts, the MCP server exposes to agents, and the HTTP API serves are the same surface — a workflow you script one way is callable verbatim the others.

Universal JSON-object flags

The CLI’s own help text (the same block is appended to every triform <tool> --help output):

Universal JSON-object flags (accepted by every tool and every action):
  --input '{...}'   Merge a JSON object's keys into the top-level request
  --json '{...}'    Alias for --input
  --patch '{...}'   Alias for --input
  --meta '{...}'    Alias for --input

All four take one JSON OBJECT (not array/scalar); its keys are merged at
the top level of the request body, ADDING to any --field flags already
given. Example (op-uat update_meta recipe):
  triform element update_meta --slug my-elem --meta '{"key":"value"}'