@r-cli/replicate

A powerful CLI tool for interacting with the Replicate API. List models, create predictions, and manage your AI workflows directly from the terminal.

Installation

npm install -g @r-cli/replicate

Local Development

1. Install dependencies:

   npm install

2. Build the project:

   npm run build

3. Link globally (for development):

   npm link

   This makes the replicate command available globally on your system.

Authentication

The CLI will automatically prompt you for your API token on first use. Get your token from replicate.com/account/api-tokens.

Interactive Authentication (Recommended)

Simply run any command, and you'll be prompted to enter your API token:

replicate models:list
# 🔑 No API token found.
# Get your API token from: https://replicate.com/account/api-tokens
#
# Enter your API token: ********
# ✓ Token saved successfully!

Your token is securely stored at ~/.config/replicate/config and automatically used for all future commands.

Manual Authentication

You can also authenticate explicitly using:

replicate auth:login

Alternative Authentication Methods

The CLI checks for your API token in this order:

1. Config file (recommended): ~/.config/replicate/config
2. Environment variable: REPLICATE_API_TOKEN
3. dotenv file: .env.local or .env in current directory

To use environment variables:

export REPLICATE_API_TOKEN=your_api_token_here
replicate models:list

Or create a .env.local file:

# .env.local
REPLICATE_API_TOKEN=your_api_token_here

Managing Authentication

View current authentication status:

replicate auth:whoami

Manually set or update your token:

replicate auth:login
# or
replicate config:set token r8_your_token_here

View your configuration:

replicate config:get
# or view specific value
replicate config:get token

Logout (remove stored token):

replicate auth:logout

Usage

Models

List Models

replicate models:list

Search for models:

replicate models:list --search "text-to-image"

Output as JSON:

replicate models:list --json

Show Model Details

View model information and input schema:

replicate models:show owner/model-name

Example:

replicate models:show stability-ai/stable-diffusion

Predictions

Create a Prediction

Create a prediction with inline arguments:

replicate predictions:create owner/model-name --key1=value1 --key2=value2

Example:

replicate predictions:create stability-ai/stable-diffusion --prompt="A beautiful sunset" --num_outputs=2

Using a JSON input file:

replicate predictions:create owner/model-name --input-file=input.json

Combining file and inline arguments (inline arguments override file values):

replicate predictions:create owner/model-name --input-file=input.json --override_key=value

Argument Types:

• Strings: --prompt="Hello world"
• Numbers: --width=512
• Booleans: --enable_flag=true or --enable_flag=false
• JSON arrays/objects: Use a JSON input file

Find required arguments: Use models:show to see what arguments a model accepts:

replicate models:show owner/model-name

Get Prediction Status

replicate predictions:get <prediction-id>

Watch until completion:

replicate predictions:get <prediction-id> --watch

Output as JSON:

replicate predictions:get <prediction-id> --json

List Predictions

View your prediction history:

replicate predictions:list

Limit results:

replicate predictions:list --limit 10

Examples

Complete Workflow

1. Find a model:

   replicate models:list --search "image generation"

2. Check model requirements:

   replicate models:show stability-ai/stable-diffusion

3. Create a prediction:

   replicate predictions:create stability-ai/stable-diffusion \
     --prompt="A futuristic city at sunset" \
     --width=1024 \
     --height=1024 \
     --num_outputs=1

4. Check status:

   replicate predictions:get <prediction-id> --watch

5. View history:

   replicate predictions:list

Development

Project Structure

.
├── src/
│   ├── commands/          # CLI commands
│   │   ├── models/        # Model-related commands
│   │   └── predictions/   # Prediction-related commands
│   └── utils/             # Shared utilities
├── bin/                   # Executable entry point
├── lib/                   # Compiled JavaScript (generated)
└── package.json

Building

npm run build

Testing Locally

After linking with npm link, test commands:

replicate --help
replicate models:list

Troubleshooting

Authentication Issues

• Run replicate auth:whoami to verify your authentication status
• If you see "Invalid or expired API token", run replicate auth:login to re-authenticate
• Your token is stored at ~/.config/replicate/config

Command not found after npm link

• Make sure your shell has the npm bin directory in PATH
• Try: export PATH="$(npm config get prefix)/bin:$PATH"

Invalid argument errors

• Use models:show to check the model's input schema
• Ensure required fields are provided
• Check argument types match the schema (string, number, boolean)

Publishing (Maintainers)

This package uses automated publishing via GitHub Actions.

Setup (One-time)

1. Create npm token:

   • Go to https://www.npmjs.com/settings/YOUR_USERNAME/tokens
   • Create a new "Automation" token
   • Copy the token

2. Add npm token to GitHub:

   • Go to your repository settings → Secrets and variables → Actions
   • Create a new secret named NPM_TOKEN
   • Paste your npm token

Automated Workflow

On every push to main:

• Version automatically bumps based on commit messages:
  • major: breaking change → bumps major version (1.0.0 → 2.0.0)
  • feat: new feature → bumps minor version (1.0.0 → 1.1.0)
  • Any other commit → bumps patch version (1.0.0 → 1.0.1)
• Creates a git tag

To publish to npm:

1. Go to GitHub → Releases → Create a new release
2. Create a tag matching the version (e.g., v1.2.3)
3. Publish the release
4. GitHub Actions will automatically:
   • Update package.json version
   • Build the project
   • Publish to npm
   • Commit version changes back to main

Manual Publishing (Alternative)

If you prefer manual control:

# Bump version
npm version patch  # or minor/major

# Publish to npm
npm publish

# Push changes
git push --follow-tags

License

MIT