# Install & upgrade

The full install matrix (pipx recommended, pip in a venv, npx, uvx), plus tj upgrade and how to verify a fresh install.

---

TokenJam ships as a Python package on PyPI and a TypeScript SDK on npm. Pick the install that matches what you need. Everything below requires Python ≥ 3.10.

## The install matrix

| Command | Best for | Notes |
|---|---|---|
| `pipx install tokenjam` | **Recommended, all platforms** | Isolated venv for the `tj` CLI; sidesteps PEP 668 on Homebrew Python and Debian/Ubuntu |
| `pip install tokenjam` | An existing project venv | Run it inside an activated venv, not against system Python |
| `npx tokenjam` | A no-install peek | Shells out to the Python CLI via `uvx` or `pipx run` under the hood |
| `uvx tokenjam` | A no-install peek with uv | Runs the Python CLI directly; equivalent to `uvx --from tokenjam tj` |

### pipx (recommended)

```bash
pipx install tokenjam
```

`pipx` creates an isolated venv for the `tj` CLI. It works on macOS with Homebrew Python (which refuses `pip install` into its managed environment) and on Debian 12+ / Ubuntu 24+, and it won't pollute your system Python or any project venv.

Don't have `pipx`?

| Platform | Install |
|---|---|
| macOS | `brew install pipx` |
| Debian / Ubuntu | `apt install pipx` |
| Windows | `py -m pip install --user pipx` |
| Anywhere else | `python3 -m pip install --user pipx` |

Then run `pipx ensurepath` so pipx's bin directory is on your `PATH`.

### pip in a venv

```bash
python3 -m venv .venv && source .venv/bin/activate
pip install tokenjam
```

Use this when you want `tj` inside an existing project environment. Either path gives you the CLI, the local REST API (`tj serve`), and every native SDK integration.

### npx and uvx

```bash
npx tokenjam        # or:  uvx tokenjam
```

These launch the Python CLI without a persistent install. They need a Python runner (`uv` or `pipx`) already present. `npx tokenjam` runs the thin `tokenjam` npm wrapper, which finds the first available runner and passes every argument straight through, so `npx tokenjam optimize` and `uvx tokenjam cost` both work.

## Upgrading

```bash
tj upgrade
```

`tj upgrade` installs the new package and restarts the daemon in one step. The restart is the part people miss: a running daemon keeps serving the old code until it is replaced.

To upgrade through your package manager instead:

```bash
pipx upgrade tokenjam          # if you installed via pipx (recommended)
pip install --upgrade tokenjam # if you're in a pip + venv setup
```

After a manual upgrade:

1. Restart the daemon so it picks up the new code: `tj stop && tj serve &`
2. Confirm the version: `tj --version`
3. Run a health check: `tj doctor`

Database migrations apply automatically on the next `tj` invocation, so there's no manual migration step.

PyPI's CDN occasionally lags a minute or two after a release. If `pipx upgrade` reports "already at the latest version" but `tj --version` is older than the [releases page](https://github.com/Metabuilder-Labs/tokenjam/releases), wait a moment and retry.

## Verify a fresh install

```bash
tj doctor
```

`tj doctor` checks config validity, DB connectivity, ingest-secret presence, and daemon health. Exit code 0 means clean, 1 means warnings, and 2 means errors.

To confirm telemetry is actually flowing (not just that setup finished), run `tj ping` — it emits one labeled test span and reports where it landed.