> ## Documentation Index
> Fetch the complete documentation index at: https://thinkwell.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI Reference

> Complete reference for the thinkwell command-line interface.

The `thinkwell` CLI is the primary way to run and build Thinkwell agent scripts.

## Usage

```bash theme={null}
thinkwell <script.ts> [args...]     # Run a TypeScript script
thinkwell run <script.ts> [args...] # Explicit run command
thinkwell init                      # Initialize thinkwell in current directory
thinkwell new <project-name>        # Create a new project in a new directory
thinkwell check                     # Type-check project (no output files)
thinkwell build                     # Compile project with @JSONSchema support
thinkwell bundle <script.ts>        # Compile to standalone executable
thinkwell --help                    # Show help message
thinkwell --version                 # Show version
```

## Running Scripts (Zero-Config)

The simplest way to run a Thinkwell script is to pass it directly to the CLI:

```bash theme={null}
thinkwell my-agent.ts
```

This runs your TypeScript file with native TypeScript support—no compilation step required. The CLI automatically processes `@JSONSchema` annotations.

You can pass arguments to your script after the filename:

```bash theme={null}
thinkwell my-agent.ts --input data.json --verbose
```

### The `run` Subcommand

The explicit `run` subcommand is equivalent to passing a script directly:

```bash theme={null}
thinkwell run my-agent.ts --input data.json
```

## Project Setup

### `thinkwell init`

Initialize thinkwell in an existing directory:

```bash theme={null}
thinkwell init
```

This command:

1. Creates `package.json` if none exists
2. Adds `thinkwell` and `typescript` dependencies using the detected package manager (pnpm, yarn, or npm)

Options:

* `--yes, -y` - Proceed without prompting for confirmation (CI-friendly)

### `thinkwell new`

Create a new project in a new directory:

```bash theme={null}
thinkwell new my-agent
```

This creates a new directory with:

* `package.json` with thinkwell dependency
* `tsconfig.json` for TypeScript
* `src/main.ts` with example agent code
* `.gitignore`
* `.env.example`

## Type Checking

### `thinkwell check`

Check a project for type errors:

```bash theme={null}
thinkwell check
```

This will essentially perform the same type checking as `thinkwell build` without writing any output files, which is faster for catching errors during development. In a workspace (pnpm or npm), all TypeScript packages are checked by default.

| Option                 | Description                                          |
| ---------------------- | ---------------------------------------------------- |
| `-p, --package <name>` | Check a specific workspace package (can be repeated) |
| `--pretty`             | Enable colorized output (default: true if TTY)       |
| `--no-pretty`          | Disable colorized output                             |

Exit codes:

* `0` - No type errors
* `1` - Type errors found
* `2` - Configuration error

### Examples

```bash theme={null}
# Check the current project
thinkwell check

# Check a specific workspace package
thinkwell check -p acp

# Check multiple packages
thinkwell check -p acp -p protocol

# Disable colorized output (for CI)
thinkwell check --no-pretty
```

## Building Projects

### `thinkwell build`

Compile your TypeScript project using the standard TypeScript compiler with `@JSONSchema` namespace injection:

```bash theme={null}
thinkwell build
```

This command compiles your project according to your `tsconfig.json`, applying `@JSONSchema` transformations first. Output (`.js`, `.d.ts`, source maps) is written to your configured `outDir`.

| Option                 | Description                                        |
| ---------------------- | -------------------------------------------------- |
| `-w, --watch`          | Watch for file changes and recompile               |
| `-p, --project <path>` | Path to tsconfig.json (default: `./tsconfig.json`) |
| `-q, --quiet`          | Suppress all output except errors                  |
| `--verbose`            | Show detailed build output                         |

### Examples

```bash theme={null}
# Build the project
thinkwell build

# Watch and rebuild on changes
thinkwell build --watch

# Use a specific tsconfig
thinkwell build -p tsconfig.app.json

# Suppress success output (for CI)
thinkwell build --quiet
```

### Configuration via package.json

Control which files receive `@JSONSchema` transformation:

```json theme={null}
{
  "thinkwell": {
    "build": {
      "include": ["src/**/*.ts"],
      "exclude": ["**/*.test.ts", "**/__fixtures__/**"]
    }
  }
}
```

Files not matched by `include` (or matched by `exclude`) are still compiled by TypeScript—they just skip `@JSONSchema` transformation.

## Bundling Executables

### `thinkwell bundle`

Compile your script into a standalone executable that can run without Node.js or Thinkwell installed:

```bash theme={null}
thinkwell bundle src/agent.ts
```

The resulting binary includes:

* Node.js 24 runtime with native TypeScript support
* All thinkwell packages
* Your bundled application code

### Bundle Options

| Option                  | Description                                       |
| ----------------------- | ------------------------------------------------- |
| `-o, --output <path>`   | Output file path (default: `./<name>-<target>`)   |
| `-t, --target <target>` | Target platform (can be specified multiple times) |
| `--include <glob>`      | Additional files to embed as assets               |
| `-e, --external <pkg>`  | Exclude package from bundling (can be repeated)   |
| `-m, --minify`          | Minify the bundled code for smaller output        |
| `-w, --watch`           | Watch for changes and rebuild automatically       |
| `-n, --dry-run`         | Show what would be built without building         |
| `-q, --quiet`           | Suppress all output except errors (for CI)        |
| `-v, --verbose`         | Show detailed build output                        |

### Target Platforms

| Target         | Description                |
| -------------- | -------------------------- |
| `host`         | Current platform (default) |
| `darwin-arm64` | macOS on Apple Silicon     |
| `darwin-x64`   | macOS on Intel             |
| `linux-x64`    | Linux on x64               |
| `linux-arm64`  | Linux on ARM64             |

### Examples

```bash theme={null}
# Bundle for current platform
thinkwell bundle src/agent.ts

# Specify output path
thinkwell bundle src/agent.ts -o dist/my-agent

# Bundle for Linux
thinkwell bundle src/agent.ts --target linux-x64

# Multi-platform build
thinkwell bundle src/agent.ts -t darwin-arm64 -t linux-x64

# Preview build without executing
thinkwell bundle src/agent.ts --dry-run

# Keep sqlite3 as external dependency
thinkwell bundle src/agent.ts -e sqlite3

# Minify for smaller binary
thinkwell bundle src/agent.ts --minify

# Watch mode for development
thinkwell bundle src/agent.ts --watch
```

### Configuration via package.json

Set bundle defaults in your `package.json`:

```json theme={null}
{
  "thinkwell": {
    "bundle": {
      "output": "dist/my-agent",
      "targets": ["darwin-arm64", "linux-x64"],
      "external": ["sqlite3"],
      "minify": true
    }
  }
}
```

CLI options override `package.json` settings.

<Note>
  Binaries are approximately 70-90 MB due to the embedded Node.js runtime. The `--minify` flag reduces bundle size, though the Node.js runtime dominates the total size.
</Note>

## Environment Variables

| Variable              | Description                                                             |
| --------------------- | ----------------------------------------------------------------------- |
| `THINKWELL_AGENT`     | Override the agent name (see [supported names](#supported-agent-names)) |
| `THINKWELL_AGENT_CMD` | Override the agent command (e.g., `myagent --acp`)                      |
| `THINKWELL_CACHE_DIR` | Override the cache directory (default: `~/.cache/thinkwell`)            |
| `DEBUG`               | Enable debug output for troubleshooting                                 |

The agent environment variables let you swap agents at runtime without modifying code. For example, a script that calls `open('claude')` can be run with a different agent:

```bash theme={null}
# Run with OpenCode instead of Claude
THINKWELL_AGENT=opencode thinkwell my-script.ts

# Run with a custom agent command
THINKWELL_AGENT_CMD="myagent --acp" thinkwell my-script.ts
```

If both are set, `THINKWELL_AGENT_CMD` takes precedence.

### Supported Agent Names

| Name       | Command                                        |
| ---------- | ---------------------------------------------- |
| `claude`   | `npx -y @agentclientprotocol/claude-agent-acp` |
| `codex`    | `npx -y @zed-industries/codex-acp`             |
| `gemini`   | `npx -y @google/gemini-cli --experimental-acp` |
| `kiro`     | `kiro-cli acp`                                 |
| `opencode` | `opencode acp`                                 |
| `auggie`   | `auggie --acp`                                 |