CLI Reference

Complete command-line reference for the berth CLI.

Overview

berth <command> [options]

Install via Homebrew:

brew tap berth-app/berth
brew install berth-app/berth/berth-cli

Projects can be identified by name or UUID. Most commands that interact with remote agents accept a --target flag (defaults to local).

Project Commands

berth list

List all projects with their status, runtime, and metadata.

berth list

berth deploy <path>

Deploy code from a directory or file. Creates the project and runs it.

Option	Description	Default
`--name <name>`	Project name (defaults to directory name)	—
`--target <target>`	Deploy target	`local`

# Deploy local directory
berth deploy ./my-project

# Deploy to a remote target with a custom name
berth deploy ./scraper --name hn-scraper --target my-vps

berth run <project>

Run a project and stream output.

Option	Description	Default
`--target <target>`	Target to run on	`local`
`--mode <mode>`	Run mode: `oneshot` or `service`	`oneshot`
`--port <port>`	Port the service listens on (service mode)	`0`

# Run locally
berth run my-project

# Run as a service on a remote target
berth run my-api --target my-vps --mode service --port 8080

berth stop <project>

Stop a running project.

Option	Description	Default
`--target <target>`	Target to stop on	`local`

berth stop my-project
berth stop my-project --target my-vps

berth logs <project>

View logs for a project. Runs the project and captures output.

Option	Description	Default
`-f, --follow`	Follow log output (stream in real-time)	`false`
`--target <target>`	Target to read logs from	`local`

berth logs my-project --follow
berth logs my-project --target my-vps -f

berth status <project>

Get detailed status of a project including run history.

berth status my-project

berth import <path>

Import code as a new project without running it.

Option	Description	Default
`--name <name>`	Project name	—

berth import ./my-code --name my-project

berth detect <path>

Auto-detect the runtime, entrypoint, and dependencies for a directory or file.

berth detect ./my-project

berth delete <project>

Delete a project and its files.

berth delete my-project

berth health

Check system health and version.

berth health

Target Commands

berth targets list

List all configured deploy targets.

berth targets list

berth targets add <name>

Add a new remote deploy target.

Option	Description	Default
`--host <host>`	Agent host address (IP or hostname)	Required
`--port <port>`	Agent port	`50051`

berth targets add my-vps --host 192.168.1.100
berth targets add staging --host staging.example.com --port 50051

berth targets remove <name>

Remove a deploy target.

berth targets remove my-vps

berth targets ping <name>

Check health of a target's agent. Shows agent version, uptime, OS, CPU, and memory.

berth targets ping my-vps

Schedule Commands

berth schedule add <project> <cron>

Add a cron-like schedule to a project.

# Run every hour
berth schedule add my-scraper "@hourly"

# Run every 5 minutes
berth schedule add my-monitor "@every 5m"

# Run at 9:30 AM daily
berth schedule add my-report "30 9 * * *"

berth schedule list

List all schedules across all projects.

berth schedule list

berth schedule remove <schedule-id>

Remove a schedule by its UUID.

berth schedule remove 550e8400-e29b-41d4-a716-446655440000

Publish Commands

berth publish <project>

Publish a running project to a public URL via a tunnel provider.

Option	Description	Default
`--port <port>`	Local port the service listens on	`8080`
`--provider <provider>`	Tunnel provider	`cloudflared`
`--target <target>`	Target where the project runs	`local`

berth publish my-api --port 8080
berth publish my-api --port 3000 --target my-vps

berth unpublish <project>

Stop the public URL tunnel for a project.

Option	Description	Default
`--target <target>`	Target	`local`

berth unpublish my-api

Environment Variable Commands

berth env set <project> <key> <value>

Set an environment variable for a project.

berth env set my-bot API_KEY sk-abc123
berth env set my-bot DATABASE_URL "postgres://user:pass@host/db"

berth env list <project>

List all environment variables for a project. Values are masked.

berth env list my-bot

berth env remove <project> <key>

Remove an environment variable.

berth env remove my-bot API_KEY

berth env import <project> <file>

Import environment variables from a .env file. Merges with existing variables (upsert).

berth env import my-bot .env

Template Store Commands

berth store list

List available templates from the Berth Template Store.

Option	Description	Default
`--category <cat>`	Filter by category: `scrapers`, `api-servers`, `bots`, `ai-ml`	—

berth store list
berth store list --category scrapers

berth store search <query>

Search templates by keyword.

berth store search "web scraper"

berth store install <template-id>

Install a template, creating a new project ready to run.

berth store install hn-scraper
berth store install fastapi-starter