Durable actors CLI reference

Install

Requires Node.js 22.19 or later.

npx terse-cli install
terse --help

Create a project

terse init my-agent
terse init my-python-agent --language python

TypeScript starts in src/actor.ts. Python starts in src/actor.py. terse.config.json identifies the hosted project. For unattended setup, authenticate first:

terse init my-agent --non-interactive --yes

Run locally

Run from the actor project:

terse actor dev

The server watches your source. The default endpoint is http://127.0.0.1:7100/v1/projects/local/actors. Local state lives in .durable-actors/. Keep that directory to retain state.

Option	Default	Purpose
`--port <port>`	`7100`	Set the local server port.
`--project-id <id>`	`local`	Set the local project ID.

Generate a client

Keep the actor server running. Run from your application project:

terse actor generate --language typescript
terse actor generate --language python

Option	Purpose
`--language typescript\|python`	Select the client language. Omit to infer from the contract.
`--out-dir <directory>`	Set the generated directory.
`--yes`	Approve missing Python prerequisites and dependencies.
`--non-interactive`	Disable prompts.

TypeScript defaults to src/terse.actors/. Python defaults to generated/. Python generation requires a pyproject.toml with a [project] table. TypeScript generation requires a compatible terse-sdk in the application. Generate TypeScript clients from TypeScript actors. Python actors currently expose Python client contracts. Use the matching language for the quickstart. Regenerate after changing public methods, state, or socket types. Keep generated files unchanged.

Deploy

Run from the actor project:

terse deploy

The CLI checks the actor contract and uploads source. Python definitions undergo strict mypy checks. TypeScript definitions undergo type checking. The CLI prints the hosted actor URL. Set that URL in the calling application. Set its TERSE_API_KEY. Regenerate the client against the hosted contract.

Secrets

terse secrets add OPENAI_API_KEY
terse secrets list
terse secrets import .env
terse secrets remove OPENAI_API_KEY

add prompts for the value. --value-stdin reads it from standard input. Local sync writes the value to .env; --skip-local-sync disables that write. import --overwrite replaces existing server values. list --json lists names. Keep provider keys in the actor project. Keep Terse credentials in the calling backend. Keep both out of browser code.

Connection settings

Variable	Consumer	Purpose
`TERSE_ACTOR_URL`	Client and generator	Full actor endpoint. Defaults to the local URL above.
`TERSE_API_KEY`	Client and CLI	Credential for the selected Terse backend or protected runtime.
`TERSE_ACTOR_PORT`	Local server	Port override. `--port` takes precedence.
`TERSE_ACTOR_PROJECT_ID`	Local server	Project override. `--project-id` takes precedence.
`TERSE_ACTOR_SECRET`	Local server	Enable local authentication. Set the same client `TERSE_API_KEY`.
`DURABLE_ACTORS_DATA_DIR`	Local server	Override local state storage.
`DURABLE_ACTORS_PYTHON`	Python tooling	Select the Python interpreter.

Create an API token in the app under your profile menu → API tokens. Copy it into the backend’s TERSE_API_KEY. The CLI loads .env. Application backends must load their own environment. Saved CLI credentials can authorize hosted client generation; running applications still need TERSE_API_KEY.

Account and utilities

Command	Purpose
`terse auth login`	Sign in.
`terse auth logout`	Clear saved credentials.
`terse auth status`	Show authentication status.
`terse auth org list`	List organizations.
`terse auth org switch [org-id]`	Select an organization.
`terse target status`	Show the selected backend.
`terse target use [preset]`	Select backend and frontend targets.
`terse target clear`	Clear target overrides.
`terse update`	Update the CLI.
`terse dashboard`	Open the app.
`terse docs`	Open the docs.
`terse completion install`	Install shell completion.
`terse completion uninstall`	Remove shell completion.

Run terse <command> --help for command options.

Get started

Reference

Durable actors CLI reference

Install

Create a project

Run locally

Generate a client

Deploy

Secrets

Connection settings

Account and utilities

​Install

​Create a project

​Run locally

​Generate a client

​Deploy

​Secrets

​Connection settings

​Account and utilities

Install

Create a project

Run locally

Generate a client

Deploy

Secrets

Connection settings

Account and utilities