Metadata-Version: 2.4
Name: wafer-cli
Version: 0.2.25
Summary: CLI for running GPU workloads, managing remote workspaces, and evaluating/optimizing kernels
Requires-Python: >=3.11
Description-Content-Type: text/markdown
Requires-Dist: typer>=0.12.0
Requires-Dist: trio>=0.24.0
Requires-Dist: trio-asyncio>=0.15.0
Requires-Dist: wafer-core>=0.1.0
Requires-Dist: perfetto>=0.16.0
Requires-Dist: posthog>=3.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"
Requires-Dist: diff-cover>=8.0.0; extra == "dev"
Requires-Dist: ruff>=0.4.0; extra == "dev"

# Wafer CLI

Wafer CLI gives coding agents direct access to GPU docs, trace analysis, and remote kernel evaluation.
It helps you develop and optimize GPU kernels even when you are not working on a machine with a GPU.

## Key features

- Query GPU documentation with citations
- Analyze GPU traces and profiles
- Evaluate kernels on remote GPUs for correctness and performance
- Run commands on GPU targets (remote or local)
- Manage persistent workspaces

## Quick start

```bash
uv tool install wafer-cli
wafer login
wafer remote-run -- nvidia-smi
```

## Common commands

```bash
wafer workspaces list
wafer workspaces create my-workspace --wait
wafer agent -t ask-docs --corpus cuda "What causes shared memory bank conflicts?"
wafer agent -t trace-analyze --args trace=./profile.ncu-rep "Why is this kernel slow?"
wafer evaluate --impl kernel.py --reference ref.py --test-cases tests.json --benchmark
wafer nvidia ncu analyze profile.ncu-rep
wafer corpus list
```

## Typical workflows

### Query GPU documentation

Download a documentation corpus and ask questions with citations.

```bash
wafer corpus download cuda
wafer agent -t ask-docs --corpus cuda "What causes shared memory bank conflicts?"
```

### Analyze performance traces

Use the trace analysis template or query trace data directly.

```bash
wafer agent -t trace-analyze --args trace=./profile.ncu-rep "Why is this kernel slow?"
wafer nvidia perfetto query trace.json \
  "SELECT name, dur/1e6 as ms FROM slice WHERE cat='kernel' ORDER BY dur DESC LIMIT 10"
```

### Evaluate kernels on remote GPUs

Run correctness and performance checks on a remote target.

```bash
wafer evaluate \
  --impl ./kernel.py \
  --reference ./reference.py \
  --test-cases ./tests.json \
  --benchmark
```

### Run commands on a remote GPU

```bash
wafer remote-run -- nvidia-smi
wafer remote-run --upload-dir ./my_code -- python3 train.py
```

### Manage workspaces

```bash
wafer workspaces list
wafer workspaces create my-workspace --wait
wafer workspaces ssh <workspace-id>
wafer workspaces delete <workspace-id>
```

## Install the CLI skill (optional)

```bash
wafer skill install
# or
wafer skill install -t <claude/codex>
```
