terse-cli

CLI for scaffolding, testing, and deploying Terse workflows.

Terse is the AI workflow platform for coding agents. You write workflows in TypeScript, generate a typed SDK from your connected integrations, and deploy serverlessly. Full docs at docs.useterse.ai.

Install

npm install -g terse-cli

Quickstart

terse init my-project
cd my-project
terse test
terse deploy

terse init scaffolds the project, installs dependencies, runs terse auth login, walks you through integrations, and runs terse generate to produce a typed SDK from your workspace.

See the full quickstart for a guided walkthrough.

Commands

| Command | What it does | |---|---| | terse init [name] | Scaffold a new project. Runs login, integrations review, and terse generate. | | terse attach | Link an existing repo to Terse in self-hosted mode. | | terse generate | Refresh src/terse.generated.ts with helpers for your connected integrations. | | terse actor dev | Run local actors, watch source changes, and print app connection settings. | | terse actor generate | Generate actor clients from the server selected by TERSE_ACTOR_URL. | | terse integrate | Connect, disconnect, or refresh integrations from the terminal. | | terse test [job] | Run a workflow locally against a real or sample trigger event. | | terse deploy | Package and deploy all workflows. Removed workflows are deleted remotely. | | terse replay <run-id> | Re-run a past run's trigger event against your local code. | | terse history [job] | List past runs or fetch full chat events for a single run. | | terse dashboard | Open the Terse web app. | | terse auth login / terse auth logout / terse auth status | Manage CLI credentials. Use terse auth org switch to change the active organization. | | terse docs | Open the docs site. |

Full flag reference for every command: docs.useterse.ai/reference/cli.

Environment

| Variable | Description | |---|---| | TERSE_API_KEY | Your user token. Every command that talks to the control plane uses it. Resolved from the process environment (including a project .env) first, then from the credentials terse auth login stores per user. | | TERSE_PROJECT_KEY | Project-scoped token used only by running workflow code. Injected automatically in Terse Cloud sandboxes; printed by terse attach for a self-hosted data plane. terse run and terse test derive it from your user token, so you never set it locally. | | TERSE_SIGNING_SECRET | Self-hosted data planes only. HMAC key used to verify that incoming triggers came from the control plane. | | TERSE_BACKEND_URL | Point the CLI at a self-hosted control plane. Defaults to https://api.useterse.ai. |

Self-hosted layouts

If your app keeps workflow definitions outside the default entry file (src/terse.jobs.ts), pass --entry-file to terse test and terse deploy:

terse test --entry-file src/server.ts
terse deploy --entry-file src/server.ts

See self-hosting for the full setup.

Local development

Developing actors

Install your actor project's dependencies and export your actors from src/actors.ts. From that project's root, alongside package.json and tsconfig.json, start a local instance:

terse actor dev

Keep it running while you develop. It downloads the matching actor runtime on first use, watches your TypeScript files, and keeps actor state in .durable-actors/. Add that directory to your .gitignore.

Local development defaults to port 7100, project local, and no API key. It does not use the cloud project ID from terse.config.json or require a cloud connection. The SDK and client generator share these defaults, including when your app is in a separate repository. No connection environment variables are needed.

Once the runtime is ready, generate clients from your app project, then start your app:

terse actor generate
npm run dev

Your app needs terse-sdk installed. Generated clients in src/terse.actors/ use the same connection settings for RPC calls and WebSocket authorization.

After changing an actor's public API, wait for the runtime to compile it successfully, then rerun terse actor generate in the consuming app. Implementation changes are watched automatically.

To override the server defaults, use --port 7101 (or TERSE_ACTOR_PORT), --project-id my-project (or TERSE_ACTOR_PROJECT_ID), or TERSE_ACTOR_SECRET. Flags take precedence over environment variables. The server prints only the client settings that need changing. Put those overrides in your app backend's .env:

# Example: a server using --port 7101
TERSE_ACTOR_URL=http://127.0.0.1:7101/v1/projects/local/actors
# Only when the server has TERSE_ACTOR_SECRET configured:
# TERSE_API_KEY=<matching secret>

The CLI loads .env automatically; your app must load it itself. Keep any API key in the backend; browsers receive WebSocket grants from your backend. To connect to deployed actors, explicitly set their TERSE_ACTOR_URL and TERSE_API_KEY. Remove those overrides to return to the local defaults.

Developing the CLI

This package lives in a pnpm workspace alongside terse-sdk and terse-types. From the repo root:

pnpm install
pnpm run dev
pnpm run install-global