# CLI

> Every runnel command: signing in, running jobs locally, deploying definitions, and finding, retrying and cancelling runs from the terminal.

Source: https://galley.themes.dev/docs/reference/cli/

The `runnel` CLI talks to the same API as the dashboard. It ships with the TypeScript SDK as `npx runnel`, and as a standalone binary for Python and Go projects. Every command reads `RUNNEL_API_KEY` and `RUNNEL_ENV` when they are set, and falls back to the credentials stored by `runnel login`.

```bash
# macOS and Linux
brew install runnel/tap/runnel

# or with the TypeScript SDK
npm install @runnel/sdk
npx runnel --version
```

## Global flags

| Flag | Description |
|---|---|
| `--env <name>` | Environment to act on. Defaults to `RUNNEL_ENV`, then `development`. |
| `--project <name>` | Project to act on. Defaults to `project` in `runnel.config.ts`. |
| `--json` | Print machine-readable JSON instead of tables. |
| `--url <url>` | API address for a self-hosted Runnel Server. Defaults to `RUNNEL_URL`. |

## Account and local development

### runnel login

Opens your browser, asks you to approve the CLI and stores a token in `~/.config/runnel/credentials`. On a server without a browser, pass `--no-browser` and paste the code it prints.

### runnel dev

Starts a local Runnel server and your worker side by side, and restarts the worker when a file changes. The dashboard runs on `http://localhost:8288`. Runs, schedules and logs stay on your machine and nothing is sent to Runnel Cloud.

```bash
npx runnel dev
# ▸ Runnel dev server   http://localhost:8288
# ▸ Worker              src/worker.ts (3 jobs, 1 workflow, 1 schedule)
# ▸ Watching            src/**
```

> **Tip** Use `runnel dev --port 9000` if 8288 is taken, and `--no-schedules` to stop schedules firing while you work.

## Deploying

### runnel deploy

Reads your worker entry point, collects every job, workflow and schedule it registers, and uploads their definitions as a new version of the project. Workers you start afterwards pick up the new version; runs already in progress finish on the version they started with.

```bash
runnel deploy --env production
# ✓ Registered 4 jobs, 2 workflows, 3 schedules
# ✓ Version v42 is live in production
```

`--dry-run` prints the changes without applying them. See [Deploying workers](/docs/guides/deploying/) for running deploys from CI.

## Working with runs

### runnel runs list

Lists recent runs, newest first. Filter with `--job`, `--status` (`queued`, `running`, `retrying`, `succeeded`, `failed`, `cancelled`) and `--limit` (default 20, at most 100).

```bash
runnel runs list --job send-invoice --status failed --limit 5
```

### runnel runs retry

Queues a failed or cancelled run again, with the same payload and run id. The attempt counter starts over. For workflows, `--from-step <name>` replays the run from that step: the steps before it keep their stored results and the steps from it onwards run again.

```bash
runnel runs retry run_01JB7X2K9Q4MZ8 --from-step charge-card
```

### runnel runs cancel

Cancels a queued or running run. A running attempt receives a cancellation signal through `ctx.signal` and has 30 seconds to stop before the worker abandons it.

### runnel logs

Prints the logs of a run, or of every run of a job with `--job`. `--follow` keeps streaming new lines, and `--since 1h` limits how far back it reads.

```bash
runnel logs run_01JB7X2K9Q4MZ8 --follow
runnel logs --job send-invoice --since 30m
```

## Environments and keys

| Command | Description |
|---|---|
| `runnel env list` | Lists the project's environments and their current versions. |
| `runnel env create <name>` | Creates an environment, such as `preview-482`. |
| `runnel keys create --env <name>` | Creates an API key for an environment and prints it once. |
| `runnel keys revoke <key-id>` | Revokes a key. Workers using it stop within a minute. |

> **Warning** `runnel keys create` prints the secret only once. Store it in your secret manager straight away; Runnel keeps only a hash.