CodePier CLI

Installation

macOS / Linux

curl -fsSL https://get.codepier.dev | sh

Windows (PowerShell)

irm https://get.codepier.dev/install.ps1 | iex

Download binaries

Pre-built binaries for every platform:

• codepier-darwin-arm64 — macOS Apple Silicon
• codepier-darwin-x64 — macOS Intel
• codepier-linux-arm64 — Linux ARM64
• codepier-linux-x64 — Linux x64
• codepier-windows-x64.exe — Windows x64

Verify

codepier --version

Configuration

Create a codepier.yaml file in the root of your project. This file tells the CLI how to swap your deployment, what to sync, and how to route traffic.

sync

Paths to synchronize between your local machine and the pod. Each entry maps a local path to a container path separated by a colon.

sync:
  - "./src:/app/src"
  - "./package.json:/app/package.json"

image

The development image to use for the swapped pod. Can be a single string or an architecture-specific map.

# Single image
image: "node:20-slim"

# Architecture-specific images
image:
  arm64: "myregistry/dev-image:arm64"
  amd64: "myregistry/dev-image:amd64"

forward

Ports to make reachable from your machine. Two forms, because there are two different things worth forwarding.

A local:remote string forwards into the pod that codepier up hot-swapped. It only means anything while a swap is running.

forward:
  - "3000:3000"
  - "9229:9229"  # Node.js debugger

An object forwards a cluster service to a local port, served by codepier forward. No hot swap, no proxy, no certificate — a port on localhost, which is what a connection string wants.

forward:
  - service: postgres
    port: 5432
    localPort: 50444   # keeps clear of a local postgres
  - service: redis
    port: 6379
    localPort: 50637
  - service: typesense
    port: 8108
  - service: kafka
    port: 9092
    namespace: shared  # a datastore in another namespace

• service — the service name, as kubectl get svc lists it.
• port — the port on the service.
• localPort — the port to bind here. Defaults to port. Worth moving for anything that also runs locally: a forwarded cluster postgres on 5432 is indistinguishable from a local one.
• namespace — override for this entry. Defaults to the first namespaces value.

Use this rather than proxy for anything that is not HTTP. The proxy terminates TLS and routes on a Host header; postgres opens a socket and starts talking its own binary protocol with no hostname anywhere in it, so there is nothing for a proxy to route on. Databases, caches, search indexes and brokers belong here.

namespaces

Kubernetes namespace(s) to target. A single string skips the interactive prompt. An array lets you limit the choices.

# Single namespace — skips prompt
namespaces: "staging"

# Multiple namespaces — prompts to choose
namespaces:
  - "staging"
  - "development"

workload

Workload name(s) to target. Same behavior as namespaces — a single value skips the prompt. The legacy deployment field is still accepted as an alias.

# Single workload — skips prompt
workload: "api-server"

# Multiple workloads — prompts to choose
workload:
  - "api-server"
  - "worker"

kind

The workload kind to target. Defaults to Deployment. For DaemonSet workloads the swap pod is pinned to a single node — you'll be prompted to pick one, or you can pass --node.

kind: "StatefulSet"  # or "Deployment" (default), "DaemonSet"

ignore

Gitignore-style patterns to exclude from file sync. Useful for keeping large directories like node_modules or build artifacts out of the sync.

ignore:
  - "node_modules"
  - ".git"
  - "dist"
  - "*.log"

supplemental

When true, adds a new sidecar container to the pod instead of replacing the existing one. Useful when you need the original container to keep running alongside your dev environment.

supplemental: true

cache

Persistent cache volumes that survive pod restarts. Ideal for package manager caches, build caches, or any directory you want to persist between sessions. You can use a plain path or a name:path format to give the cache a descriptive name.

cache:
  # Named caches — the name is used as the volume identifier
  - npm:~/.npm
  - pip:~/.cache/pip

  # Plain path caches
  - /app/node_modules
  - /root/.cache

workdir

The working directory inside the container. This is where the SSH session starts.

workdir: "/app"

containers

Restricts which containers can be targeted for hot-swap. Only the containers listed here will be available for selection. If omitted, all containers in the pod are available.

containers:
  - "api"

proxy

HTTPS reverse proxy entries. Each entry maps a local hostname to an upstream — either a Kubernetes service (port-forwarded automatically) or, when service is omitted, a port on your local machine. The CLI generates trusted certificates via mkcert and listens on port 443 by default (see proxyPort).

proxy:
  # Forward to a Kubernetes service
  - hostname: "api.codepier.local"
    service: "api-server"    # K8s service name
    port: 3000

  # Omit service — forward to a local port instead
  # (e.g. a dev server running on your machine)
  - hostname: "app.codepier.local"
    port: 5173

Hostnames ending in .local are automatically published via mDNS, so they resolve on your machine and across your LAN without editing /etc/hosts. The proxy forwards X-Forwarded-Host, X-Forwarded-Port, and X-Forwarded-Proto headers and supports WebSocket upgrades.

Path-prefix routes

Each entry can declare routes to send specific path prefixes to a different upstream than the host default — useful for mirroring a production ingress locally (e.g. codepier.local/auth → the API service). A prefix matches the exact path and any subpath (/auth matches /auth/github but not /authxyz). First match wins.

proxy:
  - hostname: "codepier.local"
    port: 3000               # default upstream: local dev server
    routes:
      - pathPrefix: "/auth"
        service: "api-server" # /auth/* goes to the cluster API instead
        port: 4000

remoteHostname

Overrides the Host header sent upstream. Use it when the local listen name differs from what the cluster ingress or backend expects — e.g. listen on dev.api.codepier.local but forward as api.codepier.local. Available on both top-level entries and path routes.

proxy:
  - hostname: "dev.api.codepier.local"
    remoteHostname: "api.codepier.local"
    service: "api-server"
    port: 3000

proxyPort

The HTTPS port the proxy listens on. Defaults to 443, which may require sudo — use a high port like 8443 to avoid that. Can also be set per-run with --port.

proxyPort: 8443

env

Environment variables to inject into the dev container. You can set explicit values or forward variables from your local shell with from_env: true.

env:
  - name: "NODE_ENV"
    value: "development"

  - name: "DATABASE_URL"
    value: "postgresql://localhost:5432/mydb"

  # Forward from your local shell
  - name: "AWS_ACCESS_KEY_ID"
    from_env: true

  - name: "AWS_SECRET_ACCESS_KEY"
    from_env: true

Commands

# Interactive — prompts for namespace, workload, and container
codepier up

# Non-interactive — skip all prompts
codepier up --namespace staging --deployment api-server --container api

# DaemonSet swap pinned to a specific node
codepier up --deployment log-agent --node worker-2

codepier down

# SSH into the default container
codepier ssh

# SSH into a specific container
codepier ssh --container worker

# Run a build inside the container
codepier exec -- pnpm run build

# Exit code propagates — usable in a shell conditional
codepier exec -- pnpm test && echo "green"

# Override the working directory
codepier exec --cwd /app/packages/db -- pnpm run migrate

# Follow the live session if there is one, else container logs
codepier tail

# Tail a specific container
codepier tail --container api

# Ignore the live session and read the container's own logs
codepier tail --container-logs

# Start the proxy (listens on 443 by default)
codepier proxy

# Listen on a non-privileged port instead
codepier proxy --port 8443

# Start proxy and run a command once ready.
# Runs in a shell (pipes, && etc. work) and the mkcert CA is passed
# via NODE_EXTRA_CA_CERTS so child processes trust the proxy.
codepier proxy --exec "pnpm run codegen && pnpm dev"

# Hold every service in codepier.yaml open
codepier forward

# Just the one
codepier forward --service postgres

# Bring the tunnels up, then start your dev server through them.
# Waits until every tunnel answers before handing over, so the first
# query of a run doesn't race its own database.
codepier forward --exec "pnpm dev"

codepier clean

codepier sync-status

# Run any mutagen command
codepier mutagen sync list
codepier mutagen sync monitor

# Activate a Mutagen license
codepier mutagen license activate <license-key>

codepier update

codepier uninstall

Coding Agents

A coding agent dropped into a CodePier project can't tell that your code runs in a Linux container in a cluster rather than on your machine. It installs dependencies locally, the two-way file sync mirrors the result into the pod, and the build breaks.

codepier skills writes an agent skill into your project that fixes this. The skill teaches the agent to read your codepier.yaml, translate between local and container paths, route build-critical commands through codepier exec, and leave the session lifecycle to you.

# Run from your project root, next to codepier.yaml
codepier skills

# Installs to .claude/skills/codepier/
# Overwrite an existing copy after a CLI update:
codepier skills --force

The skill ships inside the CLI binary and is stamped with the CLI version, so you can tell at a glance when an installed copy has fallen behind. It works with any agent that reads the .claude/skills convention. Commit it so your whole team gets the same behavior.

Global Options

These flags can be passed to any command.

Examples

Getting Started

The simplest possible config. Swaps a deployment with a dev image, syncs your entire project, and caches npm packages between sessions.

workload: hello-world
namespaces:
  - hello-world

image: node:24-slim

workdir: /opt/hello-world

sync:
  - ".:/opt/hello-world"

ignore:
  - "node_modules"
  - ".git"

cache:
  - npm:~/.npm

Node.js API with Port Forwarding

A more complete setup for developing a Node.js service. Syncs specific source paths, forwards the app port and debugger, and uses named caches.

workload: api-server
namespaces:
  - staging

image: node:20-slim
workdir: /app

sync:
  - "./src:/app/src"
  - "./package.json:/app/package.json"
  - "./tsconfig.json:/app/tsconfig.json"

forward:
  - "3000:3000"
  - "9229:9229"

ignore:
  - "node_modules"
  - "dist"
  - ".git"
  - "*.log"

cache:
  - npm:~/.npm

env:
  - name: "NODE_ENV"
    value: "development"

Multi-Service with HTTPS Proxy

Route local HTTPS traffic to Kubernetes services and a local dev server, mirroring the production ingress with path routes. Run codepier proxy to start the reverse proxy, then access each service via its hostname — the .local names resolve automatically via mDNS.

namespaces: "staging"
workload: "api-server"

image: "node:20-slim"
workdir: "/app"

sync:
  - ".:/app"

forward:
  - "3000:3000"

ignore:
  - "node_modules"
  - ".git"

cache:
  - "/app/node_modules"

proxyPort: 8443

proxy:
  # Local dev server, with /auth handled by the cluster API
  - hostname: "app.codepier.local"
    port: 5173
    routes:
      - pathPrefix: "/auth"
        service: "api-server"
        port: 4000

  - hostname: "api.codepier.local"
    service: "api-server"
    port: 3000

  - hostname: "auth.codepier.local"
    service: "auth-service"
    port: 4000

env:
  - name: "NODE_ENV"
    value: "development"
  - name: "API_URL"
    value: "https://api.codepier.local:8443"

Multi-Architecture with Supplemental Container

Use architecture-specific images and add a sidecar container instead of replacing the original. This is useful when you need the original container's processes to keep running alongside your dev environment.

namespaces:
  - "staging"
  - "production"

workload:
  - "worker"
  - "scheduler"

kind: "Deployment"
supplemental: true

image:
  arm64: "ghcr.io/myorg/dev-image:arm64"
  amd64: "ghcr.io/myorg/dev-image:amd64"

workdir: "/app"

sync:
  - "./src:/app/src"
  - "./config:/app/config"

forward:
  - "8080:8080"

ignore:
  - "node_modules"
  - ".git"
  - "dist"
  - "coverage"

cache:
  - "/app/node_modules"
  - "/root/.cache"

env:
  - name: "NODE_ENV"
    value: "development"
  - name: "AWS_ACCESS_KEY_ID"
    from_env: true
  - name: "AWS_SECRET_ACCESS_KEY"
    from_env: true