replicate-cli

What this skill does

# Replicate CLI

The Replicate CLI is a command-line tool for interacting with Replicate's AI model platform. It enables running predictions, managing models, creating deployments, and fine-tuning models directly from the terminal.

## Authentication

Before using the Replicate CLI, set the API token:

```bash
export REPLICATE_API_TOKEN=<token-from-replicate.com/account>
```

Alternatively, authenticate interactively:

```bash
replicate auth login
```

Verify authentication:

```bash
replicate account current
```

## Core Commands

### Running Predictions

The primary use case is running predictions against hosted models.

**Basic prediction:**
```bash
replicate run <owner/model> input_key=value
```

**Examples:**

Image generation:
```bash
replicate run stability-ai/sdxl prompt="a studio photo of a rainbow colored corgi"
```

Text generation with streaming:
```bash
replicate run meta/llama-2-70b-chat --stream prompt="Tell me a joke"
```

**Prediction flags:**
- `--stream` - Stream output tokens in real-time (for text models)
- `--no-wait` - Submit prediction without waiting for completion
- `--web` - Open prediction in browser
- `--json` - Output result as JSON
- `--save` - Save outputs to local directory
- `--output-directory <dir>` - Specify output directory (default: `./{prediction-id}`)

### Input Handling

**File uploads:** Prefix local file paths with `@`:
```bash
replicate run nightmareai/real-esrgan [email protected]
```

**Output chaining:** Use `{{.output}}` template syntax to chain predictions:
```bash
replicate run stability-ai/sdxl prompt="a corgi" | \
replicate run nightmareai/real-esrgan image={{.output[0]}}
```

### Model Operations

**View model schema** (see required inputs and outputs):
```bash
replicate model schema <owner/model>
replicate model schema stability-ai/sdxl --json
```

**List models:**
```bash
replicate model list
replicate model list --json
```

**Show model details:**
```bash
replicate model show <owner/model>
```

**Create a new model:**
```bash
replicate model create <owner/name> \
  --hardware gpu-a100-large \
  --private \
  --description "Model description"
```

Model creation flags:
- `--hardware <sku>` - Hardware SKU (see `references/hardware.md`)
- `--private` / `--public` - Visibility setting
- `--description <text>` - Model description
- `--github-url <url>` - Link to source repository
- `--license-url <url>` - License information
- `--cover-image-url <url>` - Cover image for model page

### Training (Fine-tuning)

Fine-tune models using the training command:

```bash
replicate train <base-model> \
  --destination <owner/new-model> \
  input_key=value
```

**Example - Fine-tune SDXL with DreamBooth:**
```bash
replicate train stability-ai/sdxl \
  --destination myuser/custom-sdxl \
  --web \
  [email protected] \
  use_face_detection_instead=true
```

**List trainings:**
```bash
replicate training list
```

**Show training details:**
```bash
replicate training show <training-id>
```

### Deployments

Deployments provide dedicated, always-on inference endpoints with predictable performance.

**Create deployment:**
```bash
replicate deployments create <name> \
  --model <owner/model> \
  --hardware <sku> \
  --min-instances 1 \
  --max-instances 3
```

**Example:**
```bash
replicate deployments create text-to-image \
  --model stability-ai/sdxl \
  --hardware gpu-a100-large \
  --min-instances 1 \
  --max-instances 5
```

**Update deployment:**
```bash
replicate deployments update <name> \
  --max-instances 10 \
  --version <version-id>
```

**List deployments:**
```bash
replicate deployments list
```

**Show deployment details and schema:**
```bash
replicate deployments show <name>
replicate deployments schema <name>
```

### Hardware

List available hardware options:
```bash
replicate hardware list
```

See `references/hardware.md` for detailed hardware information and selection guidelines.

### Scaffolding

Create a local development environment from an existing prediction:

```bash
replicate scaffold <prediction-id-or-url> --template=<node|python>
```

This generates a project with the prediction's model and inputs pre-configured.

## Command Aliases

For convenience, these aliases are available:

| Alias | Equivalent Command |
|-------|-------------------|
| `replicate run` | `replicate prediction create` |
| `replicate stream` | `replicate prediction create --stream` |
| `replicate train` | `replicate training create` |

Short aliases for subcommands:
- `replicate m` = `replicate model`
- `replicate p` = `replicate prediction`
- `replicate t` = `replicate training`
- `replicate d` = `replicate deployments`
- `replicate hw` = `replicate hardware`
- `replicate a` = `replicate account`

## Common Workflows

### Image Generation Pipeline

Generate an image and upscale it:
```bash
replicate run stability-ai/sdxl \
  prompt="professional photo of a sunset" \
  negative_prompt="blurry, low quality" | \
replicate run nightmareai/real-esrgan \
  image={{.output[0]}} \
  --save
```

### Check Model Inputs Before Running

Always check the model schema to understand required inputs:
```bash
replicate model schema owner/model-name
```

### Batch Processing

Run predictions and save outputs:
```bash
for prompt in "cat" "dog" "bird"; do
  replicate run stability-ai/sdxl prompt="$prompt" --save --output-directory "./outputs/$prompt"
done
```

### Monitor Long-Running Tasks

Submit without waiting, then check status:
```bash
# Submit
replicate run owner/model input=value --no-wait --json > prediction.json

# Check status later
replicate prediction show $(jq -r '.id' prediction.json)
```

## Best Practices

1. **Always check schema first** - Run `replicate model schema <model>` to understand required and optional inputs before running predictions.

2. **Use streaming for text models** - Add `--stream` flag when running language models to see output in real-time.

3. **Save outputs explicitly** - Use `--save` and `--output-directory` to organize prediction outputs.

4. **Use JSON output for automation** - Add `--json` flag when parsing outputs programmatically.

5. **Open in web for debugging** - Add `--web` flag to view predictions in the Replicate dashboard for detailed logs.

6. **Chain predictions efficiently** - Use the `{{.output}}` syntax to pass outputs between models without intermediate saves.

## Troubleshooting

**Authentication errors:**
- Verify `REPLICATE_API_TOKEN` is set correctly
- Run `replicate account current` to test authentication

**Model not found:**
- Check model name format: `owner/model-name`
- Verify model exists at replicate.com

**Input validation errors:**
- Run `replicate model schema <model>` to see required inputs
- Check input types (string, number, file)

**File upload issues:**
- Ensure `@` prefix is used for local files
- Verify file path is correct and file exists

## Additional Resources

- Replicate documentation: https://replicate.com/docs
- Model explorer: https://replicate.com/explore
- API reference: https://replicate.com/docs/reference/http
- GitHub repository: https://github.com/replicate/cli