CLI

Build, run, and inspect Tardigrade actors.

Install

bun add -g tardie

Use bunx tardie <command> to run a command without installing it. Tardigrade requires Bun 1.4 or later.

Commands

tdg init <name>

Create an actor and configure its first model provider

tdg setup

Add provider connections and choose the default model

tdg setup provider

Add or update one provider connection

tdg setup default

Choose the default model from configured providers

tdg lint <entry>

Validate an actor before building or deploying

tdg build <entry>

Build and validate an actor artifact

tdg thread create

Allocate a root thread and print its assigned identity

tdg methods

List the actor's methods and schemas

tdg call <method> <input>

Call a method with JSON input and wait for its result

tdg call state <method> <invocation>

Read an invocation's durable state

tdg call cancel <method> <invocation>

Request cancellation of an invocation

tdg events <thread>

Print a thread's event log

tdg models lock

Resolve configured models into the deployment lock

Commands that print data accept --json where their help lists it. Remote commands accept --url, --token, and --actor. The actor instance defaults to main. Run tdg <command> --help for every option.

Initialize and configure

Run interactive initialization to create a directory, choose the first provider and model, and write the generated actor:

bash

tdg init tardie-agent --template quickstart
cd tardie-agent
bun run dev

An agent or CI job can supply the connection as JSON. The JSON names secret environment variables and contains no secret values:

bash

tdg init tardie-agent \
  --template quickstart \
  --provider openrouter \
  --provider-config '{"env":["OPENROUTER_API_KEY"]}' \
  --default-model anthropic/claude-sonnet-4.6
cd tardie-agent

Non-interactive initialization requires all three provider options. It does not read or write the named credential. Set each credential in the environment that runs the server.

Run tdg setup inside an actor directory to configure the first connection and default together. After that baseline exists, add or update a connection without changing the default, or select a different default without writing credentials:

bash

tdg setup provider openai '{"env":["OPENAI_API_KEY"]}'
tdg setup default --provider openai --model gpt-5.2

Known providers supply their standard endpoint and protocol. Put additional public connection fields in the same JSON object. Amazon Bedrock requires its gateway endpoint and AWS region:

bash

tdg setup provider amazon-bedrock '{"baseUrl":"https://gateway.example.com/bedrock","region":"ap-southeast-1","env":["CLOUDFLARE_API_TOKEN"]}'

A custom provider declares its endpoint and protocol:

bash

tdg setup provider private-gateway '{"baseUrl":"https://models.example.com/v1","protocol":"openai-responses","env":["PRIVATE_MODEL_KEY"]}'

Interactive setup stores local credentials in .dev.vars with mode 0600 and adds .dev.vars* to .gitignore. It never prints a stored credential. Project configuration stays in wrangler.jsonc and celld.jsonc. Every successful setup command refreshes models.lock.json and generated/providers.ts. The generated registry imports configured model implementations; services.ts remains editable. Use tdg models lock when CI or an operator needs to refresh the lock without changing provider configuration.

Setup preserves unrelated platform settings, JSONC comments, local secret entries, and other provider connections. The model services select the provider implementation from the configured protocol. Configuration rejects unsupported protocols.

Configuration precedence

A command flag takes precedence over an environment variable. An environment variable takes precedence over ~/.tardigrade/config.json. The configuration file takes precedence over the default. This order applies to remote URL and token settings.

Setting	Flag	Environment	Default
Server to call	`--url`		`http://localhost:4242`
Bearer token	`--token`	`TARDIGRADE_TOKEN`	none
Actor instance	`--actor`		`main`
Project configuration		`TARDIGRADE_CONFIG_PATH`	`wrangler.jsonc`
Model catalog cache		`TARDIGRADE_MODEL_CATALOG_CACHE`	`.tardigrade/models.json`
Provider credentials		Variables named by each provider's `env` list	Values saved by interactive setup in `.dev.vars`

The generated bun run dev script loads .dev.vars and starts server.ts. It stores instance databases in .tardigrade/data/, with each instance's thread databases in a sibling .sqlite.threads/ directory. Keep these directories present until the server stops. A deployment reads credentials from its platform secret store. Edit server.ts to supply application Effect services or change the server composition.

Validate and run locally

Validate the actor's component and method seams before building or deploying:

bash

tdg lint actor.ts
tdg build actor.ts
bun run dev

tdg lint fails when a declared method has no handler, a component handles an absent method, several components handle the same method, or a fixed actor reference calls an undeclared method. Pass --json to inspect each method and outgoing call seam.

Discover providers and models

If your model is absent from the catalog, the interactive prompt asks for its context window, optional output limit, and tool support. Setup saves these values in the provider's model settings in wrangler.jsonc and includes them in models.lock.json.

To create a project with a custom model, include models in the provider configuration:

tdg init tardie-agent \
  --provider localhost \
  --provider-config '{"protocol":"openai-chat-completions","baseUrl":"http://localhost:8080/v1","env":["API_KEY"],"models":{"qwen-local":{"metadata":{"contextWindowTokens":32768,"toolCall":true}}}}' \
  --default-model qwen-local
cd tardie-agent

Initialization and setup use models.dev for the searchable provider and model catalog. The first interactive run saves the validated public catalog in .tardigrade/models.json. Later runs can use that snapshot. The Bun server refreshes the same cache when it starts and keeps the resolved snapshot in memory.

Call and control methods

Use tdg thread create --name root to allocate a named root before invoking it. Omit --name for a host-generated friendly name. The command prints the assigned thread ID; --json prints its actor, instance, and thread coordinates. Pass the assigned ID to --thread when calling a method.

tdg call creates a thread unless --thread names an existing thread. It waits for completion by default. Use --no-wait to print the durable handle immediately. Use the returned thread and invocation ID to read state or request cancellation:

bash

tdg methods --json
tdg thread create --name root
tdg call message '{"text":"What is the weather in Singapore?"}' --no-wait --thread root --id m1
tdg call state message m1 --thread root
tdg call cancel message m1 --thread root --reason "operator stopped it"

Reuse --id for an idempotent retry. tdg call state and tdg call cancel require the same actor instance, thread, method, and invocation ID as the original call. The server resolves the active execution epoch.

Use tdg events <thread> to inspect a thread's event log. Remote calls add the server connection and actor instance:

bash

tdg events root --url https://tardigrade.example.com --token "$TOKEN" --actor researcher
tdg events root --types TurnFailed --actor researcher

Deploy

Deploy the generated Worker through either supported platform CLI:

bash

bunx wrangler deploy
celld deploy --config celld.jsonc --dry-run
celld deploy --config celld.jsonc

Set the provider variables named by each connection in the platform secret store before the actor handles model calls. See the Cloudflare guide for Worker configuration and the Celld guide for fleet storage, variables, and rollout behavior.