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

# CLI

> Run Tamarind from your terminal, scripts, or AI agents

The Tamarind CLI (`tamarind`) lets you discover tools, submit and monitor protein, nucleic-acid, and small-molecule jobs, and download results — from your terminal, a shell script, CI, or an AI coding agent such as Claude Code or Codex.

It is a thin client over the same REST API as the [Tamarind MCP server](/tamarind/mcp-server), so the two stay in lockstep: every tool and parameter available in the API is available from the CLI. Source, installer, and issues live on [GitHub](https://github.com/Tamarind-Bio/tamarind-cli).

Use the CLI when you want to drive Tamarind from a terminal or a script. Use the [MCP server](/tamarind/mcp-server) when you want a hosted connection for claude.ai, ChatGPT, or another MCP client.

## Requirements

1. A Tamarind account — [Sign up here](https://app.tamarind.bio)
2. An API key — view yours at [app.tamarind.bio/api-docs/api-key](https://app.tamarind.bio/api-docs/api-key)
3. Python 3.10 or newer

## Installation

Install once with [`uv`](https://docs.astral.sh/uv/) or `pipx`, then run `tamarind` from anywhere:

```bash theme={null}
uv tool install tamarind-cli
# or:
pipx install tamarind-cli
```

You can also use the bootstrap installer (it installs `uv` first if needed):

```bash theme={null}
curl -fsSL https://app.tamarind.bio/cli/install.sh | sh
```

To track the latest from source:

```bash theme={null}
uv tool install "git+https://github.com/Tamarind-Bio/tamarind-cli"
```

Verify the install:

```bash theme={null}
tamarind --version
```

## Authentication

Get your API key from [app.tamarind.bio/api-docs/api-key](https://app.tamarind.bio/api-docs/api-key), then authenticate in one of two ways.

**Environment variable** — best for scripts, CI, and AI agents:

```bash theme={null}
export TAMARIND_API_KEY="YOUR_API_KEY_HERE"
```

**Stored config** — saves the key to `~/.tamarind/config.json`:

```bash theme={null}
tamarind auth login
tamarind auth status
```

## Quickstart

The end-to-end flow mirrors the platform: discover a tool, inspect its schema, validate your inputs, submit, and download results.

```bash theme={null}
# 1. Find a tool
tamarind tools --function structure-prediction --modality protein
tamarind tools --search boltz

# 2. Inspect its parameters and grab a runnable example
tamarind schema boltz
tamarind schema boltz --example > job.yaml

# 3. Validate, then submit and wait for results
tamarind validate boltz --input job.yaml
tamarind submit   boltz --input job.yaml --name my-run --wait --download ./out

# 4. Monitor anytime
tamarind jobs
tamarind status my-run
tamarind results my-run --download ./out
```

## Command reference

### Discover

| Command                  | Description                                                               |
| ------------------------ | ------------------------------------------------------------------------- |
| `tamarind tools`         | List available tools (filter with `--modality`, `--function`, `--search`) |
| `tamarind modalities`    | List modalities (protein, nucleic acid, small molecule, …)                |
| `tamarind functions`     | List tool functions (structure prediction, binder design, …)              |
| `tamarind schema <tool>` | Show a tool's parameters; `--example` prints a runnable job file          |

### Submit

| Command                                     | Description                                                          |
| ------------------------------------------- | -------------------------------------------------------------------- |
| `tamarind validate <tool> --input job.yaml` | Validate inputs without submitting                                   |
| `tamarind submit <tool> --input job.yaml`   | Submit a job (`--name`, `--wait`, `--download`, `--idempotency-key`) |
| `tamarind batch <tool> --input batch.yaml`  | Submit many jobs as one batch                                        |

### Monitor & results

| Command                                       | Description                                  |
| --------------------------------------------- | -------------------------------------------- |
| `tamarind jobs`                               | List jobs (`--status`, `--batch`, `--limit`) |
| `tamarind status <jobName>`                   | Show one job's status                        |
| `tamarind wait <jobName>`                     | Block until a job reaches a terminal state   |
| `tamarind logs <jobName>`                     | Fetch a job's logs                           |
| `tamarind results <jobName> --download ./out` | Download a job's result bundle               |

### Files & lifecycle

| Command                        | Description                                                |
| ------------------------------ | ---------------------------------------------------------- |
| `tamarind files list`          | List workspace files                                       |
| `tamarind files upload <path>` | Upload an input file                                       |
| `tamarind files delete <path>` | Delete a file                                              |
| `tamarind cancel <jobName>`    | Stop a running or queued job (`--batch` for a whole batch) |
| `tamarind delete <jobName>`    | Permanently delete a job and its data                      |

## Output & scripting

Every command is built for automation:

* **`--json`** prints machine-readable output. It is on by default when output is piped (not a terminal), so scripts and agents get JSON without any extra flags.
* **Stable exit codes** let scripts branch on failures: `0` success, `3` auth error, `4` not found, `5` validation error, `6` rate limited.
* **`--profile <name>`** switches between saved accounts or environments in `~/.tamarind/config.json`.
* **`--api-key`**, **`--api-base`**, and **`--catalog-base`** (or the matching `TAMARIND_*` environment variables) override configuration per invocation.

## Use with AI agents

The CLI is built for coding agents. Because every command takes plain flags,
emits JSON, and returns stable exit codes, an agent can drive the whole
workflow — discover a tool, write the job file, submit, and fetch results — by
running `tamarind` directly.

* **Terminal agents (Claude Code, Codex, CI):** install the CLI, set
  `TAMARIND_API_KEY`, and let the agent call `tamarind` commands. Point it at
  this page so it knows the surface.
* **Hosted / chat agents (claude.ai, ChatGPT):** connect the
  [Tamarind MCP server](/tamarind/mcp-server), which exposes the same operations
  over the Model Context Protocol.

A packaged plugin with task-specific skills (antibody design, binder design,
batch screening) is in the works — contact [info@tamarind.bio](mailto:info@tamarind.bio)
if you'd like early access.

## Troubleshooting

### `No API key configured`

Set `TAMARIND_API_KEY` or run `tamarind auth login`. Confirm with `tamarind auth status`.

### Authentication failing

Verify your key is current on the [API Key page](https://app.tamarind.bio/api-docs/api-key). Pass `--api-key` directly to rule out a stale stored key.

### `command not found: tamarind`

Ensure your tool installer's bin directory is on `PATH` (for `uv`, run `uv tool update-shell`; for `pipx`, run `pipx ensurepath`), then restart your shell.

Need help? Contact us at [info@tamarind.bio](mailto:info@tamarind.bio).

## Related Resources

* [tamarind-cli on GitHub](https://github.com/Tamarind-Bio/tamarind-cli) — source, installer, and full README
* [MCP Server](/tamarind/mcp-server) — the hosted option for claude.ai, ChatGPT, and other MCP clients
* [Full API Documentation](https://app.tamarind.bio/api-docs) — complete REST API reference
* [API Overview](/tamarind/api) — getting started with Tamarind's API