CLI Reference

The bp command-line tool for deploying and managing apps on Basepod.

Overview

bash

bp <command> [arguments] [flags]

Quick Reference

Connection Commands

Command	Description
`bp login <server>`	Connect to a Basepod server
`bp logout [name]`	Disconnect from server
`bp context [name]`	List or switch server contexts

Project Commands

Command	Description
`bp init`	Initialize basepod.yaml config
`bp deploy`	Deploy app (local, image, or git)

App Commands

Command	Description
`bp apps`	List all apps
`bp create <name>`	Create a new app
`bp start <name>`	Start an app
`bp stop <name>`	Stop an app
`bp restart <name>`	Restart an app
`bp logs <name>`	View app logs
`bp delete <name>`	Delete an app

Template Commands

Command	Description
`bp templates`	List available templates
`bp template deploy <name>`	Deploy template (predefined, file, or URL)
`bp template export <name>`	Export app config as template

Model Commands (LLM)

Command	Description
`bp models`	List LLM models
`bp model pull <model>`	Download a model
`bp model run <model>`	Start LLM server
`bp model stop`	Stop LLM server
`bp model rm <model>`	Delete a model
`bp chat`	Chat with running model

System Commands

Command	Description
`bp info`	Show server info
`bp status`	Show detailed status
`bp prune`	Clean unused resources
`bp upgrade`	Update Basepod
`bp completion <shell>`	Generate shell completion script

Connect to a Basepod server.

Syntax

bash

bp login <server>

What it does

Connects to the specified server
Prompts for password if authentication is enabled
Saves credentials to ~/.basepod.yaml
Sets as current context

Example

bash

bp login bp.example.com
# Password: ****
# Logged in to https://bp.example.com

bp logout

Disconnect from a server.

Syntax

bash

bp logout [name]

What it does

Removes server credentials from config
If no name specified, logs out from current context

Example

bash

bp logout
bp logout staging

bp context

List or switch server contexts.

Syntax

bash

bp context [name]

What it does

Without arguments: lists all saved contexts
With name: switches to that context

Example

bash

# List contexts
bp context
# * bp.example.com
#   bp.staging.example.com

# Switch context
bp context bp.staging.example.com

bp init

Initialize a project for deployment.

Syntax

bash

bp init [path]

What it does

Detects project type (Node, Go, Python, static)
Creates basepod.yaml configuration
Generates Dockerfile if needed

Flags

Flag	Short	Description
`--static`	`-s`	Force static site mode
`--container`	`-c`	Force container mode

Example

bash

cd myproject
bp init

# Detected: package.json (Node/Bun project)
# ? App name: myproject
# ? Deployment type: Container
# ? Port: 3000
# Created: basepod.yaml, Dockerfile

Detection

Found	Type
`Dockerfile`	Container (use existing)
`package.json`	Node/Bun container
`go.mod`	Go container
`requirements.txt`	Python container
`*.html` only	Static site

bp apps

List all applications.

Syntax

bash

bp apps

Aliases: app, list, ls

Example

bash

bp apps
# NAME      STATUS    DOMAIN                IMAGE
# myapp     running   myapp.example.com     node:20
# api       stopped   api.example.com       golang:latest

bp create

Create a new application.

Syntax

bash

bp create <name> [flags]

Flags

Flag	Short	Description
`--domain`	`-d`	Custom domain
`--image`	`-i`	Docker image

Example

bash

bp create myapp
bp create myapp --domain myapp.example.com
bp create myapp --image nginx:latest

bp deploy

Deploy an application. Works with local source, Docker images, or Git repositories.

Syntax

bash

bp deploy [path] [flags]

What it does

Local source (default): Reads basepod.yaml, builds and deploys
Docker image: Pulls and deploys the specified image
Git repository: Clones, builds, and deploys

Flags

Flag	Short	Description
`--image`	`-i`	Deploy from Docker image
`--git`	`-g`	Deploy from Git repository
`--branch`	`-b`	Git branch (default: main)
`--force`	`-f`	Skip git status check

Examples

bash

# Deploy local source (most common)
bp deploy

# Deploy specific directory
bp deploy ./myapp

# Deploy from Docker image
bp deploy --image nginx:latest
bp deploy --image ghcr.io/user/app:v1.0

# Deploy from Git
bp deploy --git https://github.com/user/repo.git
bp deploy --git https://github.com/user/repo.git --branch develop

# Skip uncommitted changes check
bp deploy --force

Requirements

For local source deployment:

Must have basepod.yaml (run bp init first)
Must have clean git working tree (or use --force)

bp start

Start a stopped application.

Syntax

bash

bp start <name>

Example

bash

bp start myapp
# App 'myapp' started

bp stop

Stop a running application.

Syntax

bash

bp stop <name>

Example

bash

bp stop myapp
# App 'myapp' stopped

bp restart

Restart an application.

Syntax

bash

bp restart <name>

Example

bash

bp restart myapp
# App 'myapp' restarted

bp logs

View application logs.

Syntax

bash

bp logs <name> [flags]

Flags

Flag	Short	Description
`--tail`	`-n`	Number of lines (default: 100)
`--follow`	`-f`	Stream logs in real-time

Example

bash

bp logs myapp
bp logs myapp -n 500
bp logs myapp -f

bp delete

Delete an application.

Syntax

bash

bp delete <name>

Aliases: rm

Example

bash

bp delete myapp
# Are you sure? (y/N): y
# App 'myapp' deleted

bp templates

List available one-click templates.

Syntax

bash

bp templates [flags]

Flags

Flag	Short	Description
`--category`	`-c`	Filter by category

Example

bash

bp templates
bp templates -c databases

bp template deploy

Deploy a template (predefined, local file, or URL).

Syntax

bash

bp template deploy <template|file|url> [flags]

What it does

Deploys predefined one-click templates by name
Deploys custom templates from local .yaml files
Deploys templates from remote URLs
Handles multi-service stacks

Flags

Flag	Short	Description
`--name`	`-n`	App/stack name (default: template name)
`--version`	`-v`	Image version
`--env`	`-e`	Environment variable (KEY=value)

Examples

bash

# Predefined template
bp template deploy postgres
bp template deploy postgres --name mydb --version 16
bp template deploy postgres -e POSTGRES_PASSWORD=secret

# Local template file
bp template deploy ./mystack.yaml
bp template deploy ./lamp.yaml --name mysite

# Remote template
bp template deploy https://example.com/templates/wordpress-stack.yaml

bp template export

Export an app or stack configuration as a template.

Syntax

bash

bp template export <name>

What it does

Exports running app configuration
Outputs YAML template format
Can be saved and reused

Examples

bash

# Export to stdout
bp template export myapp

# Save to file
bp template export myapp > myapp-template.yaml

# Export multi-service stack
bp template export myblog > wordpress-stack.yaml

bp models

List LLM models (Apple Silicon only).

Syntax

bash

bp models [flags]

Flags

Flag	Description
`--downloaded`	Show only downloaded models
`--category`	Filter by category (chat, code, vision)

Example

bash

bp models
# DOWNLOADED:
#   Llama-3.2-3B    2.1GB   3GB RAM
#
# AVAILABLE:
#   Mistral-7B      4.5GB   5GB RAM
#   Phi-4           8.5GB   9GB RAM

bp model pull

Download an LLM model from HuggingFace.

Syntax

bash

bp model pull <model>

What it does

Downloads model from HuggingFace
Accepts short names or full HuggingFace paths
Shows download progress

Examples

bash

# Short name (looks up in available models)
bp model pull Llama-3.2-3B

# Full HuggingFace path
bp model pull mlx-community/Llama-3.2-3B-Instruct-4bit
bp model pull mlx-community/Mistral-7B-Instruct-v0.3-4bit
bp model pull mlx-community/Qwen2.5-Coder-7B-Instruct-4bit

# Output
# Pulling mlx-community/Llama-3.2-3B-Instruct-4bit...
# Downloading: 45% [=====>    ] 1.2GB/2.1GB  ETA: 1m

bp model run

Start the LLM server with a model.

Syntax

bash

bp model run <model>

Example

bash

bp model run Llama-3.2-3B
# Server running at https://llm.example.com
# API: https://llm.example.com/v1/chat/completions

bp model stop

Stop the running LLM server.

Syntax

bash

bp model stop

bp model rm

Delete a downloaded model.

Syntax

bash

bp model rm <model>

bp chat

Interactive chat with the running LLM.

Syntax

bash

bp chat

Example

bash

bp chat
# Connected to Llama-3.2-3B
#
# You: Hello!
# AI: Hello! How can I help you today?
#
# You: /exit

bp info

Show server information.

Syntax

bash

bp info

Example

bash

bp info
# Server: https://bp.example.com
# Version: 1.0.5
# Platform: darwin/arm64
# Podman: connected
# Caddy: running

bp status

Show detailed server and app status.

Syntax

bash

bp status

bp prune

Clean up unused containers, images, and volumes.

Syntax

bash

bp prune [flags]

Flags

Flag	Description
`--all`	Include tagged images
`--dry-run`	Show what would be removed

bp upgrade

Check for updates and upgrade Basepod.

Syntax

bash

bp upgrade

bp completion

Generate shell completion scripts for tab completion.

Syntax

bash

bp completion <shell>

Supported shells: bash, zsh, fish

Setup

bash

# Bash (add to ~/.bashrc)
eval "$(bp completion bash)"

# Zsh (add to ~/.zshrc)
eval "$(bp completion zsh)"

# Fish (add to ~/.config/fish/config.fish)
bp completion fish | source

Features

Tab completion for all commands and subcommands
Auto-completes app names for start, stop, restart, logs, delete
Completes template and model subcommands

Configuration File (basepod.yaml)

The basepod.yaml file defines how your app is built and deployed.

Full Schema Reference

yaml

# App identity
name: myapp                    # Required: app name (lowercase, alphanumeric, hyphens)
type: container                # Required: "container" or "static"
domain: myapp.example.com      # Optional: custom domain (default: name.your-domain.com)
port: 3000                     # Container port your app listens on (default: 3000)

# Build configuration (for container type)
build:
  dockerfile: Dockerfile       # Path to Dockerfile (default: Dockerfile)
  context: .                   # Build context directory (default: .)
  args:                        # Build arguments passed to docker build
    NODE_ENV: production
    API_URL: https://api.example.com

# Environment variables
env:
  NODE_ENV: production
  DATABASE_URL: postgres://localhost/myapp
  SECRET_KEY: ${SECRET_KEY}    # Supports shell variable interpolation

# Persistent storage
volumes:
  - data:/app/data             # Named volume: name:/container/path
  - uploads:/app/uploads

# Resource limits
resources:
  memory: 512m                 # Memory limit (e.g., 256m, 1g)
  cpus: 1.0                    # CPU limit (e.g., 0.5, 2.0)

# SSL configuration
ssl:
  enabled: true                # Enable HTTPS (default: true)
  auto_renew: true             # Auto-renew certificates (default: true)

# Static site configuration (for type: static)
public: dist/                  # Directory containing static files

Deployment Examples

Node.js / Bun Application

Project structure:

my-node-app/
├── basepod.yaml
├── Dockerfile
├── package.json
└── src/
    └── index.js

basepod.yaml:

yaml

name: my-api
type: container
port: 3000

build:
  dockerfile: Dockerfile

env:
  NODE_ENV: production

Dockerfile:

dockerfile

FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
EXPOSE 3000
CMD ["node", "src/index.js"]

Deploy:

bash

bp deploy

Go Application

basepod.yaml:

yaml

name: go-api
type: container
port: 8080

build:
  dockerfile: Dockerfile

Dockerfile:

dockerfile

FROM golang:1.22-alpine AS builder
WORKDIR /app
COPY go.mod go.sum ./
RUN go mod download
COPY . .
RUN go build -o main .

FROM alpine:latest
COPY --from=builder /app/main /main
EXPOSE 8080
CMD ["/main"]

Python / FastAPI Application

basepod.yaml:

yaml

name: python-api
type: container
port: 8000

build:
  dockerfile: Dockerfile

env:
  PYTHONUNBUFFERED: "1"

Dockerfile:

dockerfile

FROM python:3.12-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
EXPOSE 8000
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Static Site (React, Vue, Vite, etc.)

Option 1: Pre-built (recommended for simple sites)

yaml

name: my-website
type: static
public: dist/

Build locally, then deploy:

bash

npm run build
bp deploy

Option 2: Build on server

yaml

name: my-website
type: container
port: 80

build:
  dockerfile: Dockerfile

Dockerfile:

dockerfile

FROM node:20-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html
EXPOSE 80

Docker Image Deployment

Deploy any Docker Hub image without source code:

bash

# Create app first
bp create my-nginx --domain nginx.example.com

# Deploy with image
bp deploy my-nginx --image nginx:alpine

Common images:

bash

bp deploy mydb --image postgres:16
bp deploy cache --image redis:alpine
bp deploy cms --image wordpress:latest

App with Database (Volumes)

basepod.yaml:

yaml

name: my-app
type: container
port: 3000

build:
  dockerfile: Dockerfile

env:
  DATABASE_PATH: /app/data/app.db

volumes:
  - app-data:/app/data

Data in /app/data persists across restarts and redeployments.

App with Resource Limits

basepod.yaml:

yaml

name: heavy-app
type: container
port: 8080

build:
  dockerfile: Dockerfile

resources:
  memory: 1g      # 1 GB RAM limit
  cpus: 2.0       # 2 CPU cores

App with Build Arguments

basepod.yaml:

yaml

name: my-app
type: container
port: 3000

build:
  dockerfile: Dockerfile
  args:
    VITE_API_URL: https://api.example.com
    BUILD_VERSION: "1.2.3"

Dockerfile:

dockerfile

FROM node:20-alpine AS builder
ARG VITE_API_URL
ARG BUILD_VERSION
WORKDIR /app
COPY . .
RUN npm ci && npm run build

FROM nginx:alpine
COPY --from=builder /app/dist /usr/share/nginx/html

Git Repository Deployment

Deploy directly from a git repo:

bash

bp deploy --git https://github.com/user/repo
bp deploy --git https://github.com/user/repo --branch develop

The repo must contain a basepod.yaml and Dockerfile.

Custom Domain

basepod.yaml:

yaml

name: my-app
type: container
port: 3000
domain: app.mydomain.com

build:
  dockerfile: Dockerfile

Point your DNS to your Basepod server, SSL certificates are automatic.

Environment Variables from Shell

Use ${VAR} syntax to inject local environment variables:

basepod.yaml:

yaml

name: my-app
type: container
port: 3000

env:
  API_KEY: ${API_KEY}
  DATABASE_URL: ${DATABASE_URL}

Deploy:

bash

export API_KEY="secret123"
export DATABASE_URL="postgres://..."
bp deploy

Exit Codes

Code	Description
0	Success
1	General error
2	Configuration error
3	Git error (uncommitted changes)

CLI Reference ​

Overview ​

Quick Reference ​

Connection Commands ​

Project Commands ​

App Commands ​

Template Commands ​

Model Commands (LLM) ​

System Commands ​

bp login ​

bp logout ​

bp context ​

bp init ​

bp apps ​

bp create ​

bp deploy ​

bp start ​

bp stop ​

bp restart ​

bp logs ​

bp delete ​

bp templates ​

bp template deploy ​

bp template export ​

bp models ​

bp model pull ​

bp model run ​

bp model stop ​

bp model rm ​

bp chat ​

bp info ​

bp status ​

bp prune ​

bp upgrade ​

bp completion ​

Configuration File (basepod.yaml) ​

Full Schema Reference ​

Deployment Examples ​

Node.js / Bun Application ​

Go Application ​

Python / FastAPI Application ​

Static Site (React, Vue, Vite, etc.) ​

Docker Image Deployment ​

App with Database (Volumes) ​

App with Resource Limits ​

App with Build Arguments ​

Git Repository Deployment ​

Custom Domain ​

Environment Variables from Shell ​

Exit Codes ​

CLI Reference

Overview

Quick Reference

Connection Commands

Project Commands

App Commands

Template Commands

Model Commands (LLM)

System Commands

bp login

bp logout

bp context

bp init

bp apps

bp create

bp deploy

bp start

bp stop

bp restart

bp logs

bp delete

bp templates

bp template deploy

bp template export

bp models

bp model pull

bp model run

bp model stop

bp model rm

bp chat

bp info

bp status

bp prune

bp upgrade

bp completion

Configuration File (basepod.yaml)

Full Schema Reference

Deployment Examples

Node.js / Bun Application

Go Application

Python / FastAPI Application

Static Site (React, Vue, Vite, etc.)

Docker Image Deployment

App with Database (Volumes)

App with Resource Limits

App with Build Arguments

Git Repository Deployment

Custom Domain

Environment Variables from Shell

Exit Codes