caractrl

caractrl is the command-line interface for Caravanserai. Use it to inspect nodes, manage projects, apply manifests, and forward ports from a running container to your local machine.

Global flags

Global flags control how caractrl connects to cara-server and formats its output. They must appear before the subcommand:

./bin/caractrl [--server <url>] [--output <format>] <subcommand>

string

default:"http://localhost:8080"

URL of the cara-server control plane. Override this when cara-server is not running on localhost.

string

default:"table"

Output format for command results. Accepted values: table, json, yaml.

Use --output json when you want to pipe caractrl output into tools like jq for scripting or automation:

./bin/caractrl --output json get projects | jq '.[] | select(.status.phase == "Running")'

Output format examples

table (default)
json
yaml

./bin/caractrl get projects
# NAME         PHASE     NODE       CONDITIONS          AGE
# nginx-demo   Running   worker-01  ContainersRunning   5m

./bin/caractrl --output json get projects nginx-demo
# {
#   "metadata": { "name": "nginx-demo" },
#   "status": { "phase": "Running", "nodeRef": "worker-01" }
# }

./bin/caractrl --output yaml get projects nginx-demo
# metadata:
#   name: nginx-demo
# status:
#   phase: Running
#   nodeRef: worker-01

Subcommands

version

Print the build version, commit hash, and build timestamp.

./bin/caractrl version
# caractrl v0.1.0 (commit abc1234, built 2025-01-01T00:00:00Z)

get nodes

List all nodes or inspect a single node.

./bin/caractrl get nodes [<name>]

Examples

# List all nodes
./bin/caractrl get nodes

# Inspect a single node
./bin/caractrl get nodes worker-01

# Get a single node as JSON
./bin/caractrl --output json get nodes worker-01

get projects

List all projects or inspect a single project. Filter the list by lifecycle phase with --phase.

./bin/caractrl get projects [<name>] [--phase <phase>]

Flags

Flag	Description
`--phase`	Filter by phase: `Pending`, `Scheduled`, `Running`, `Failed`, `Terminating`

Examples

# List all projects
./bin/caractrl get projects

# List only running projects
./bin/caractrl get projects --phase Running

# Inspect a single project
./bin/caractrl get projects nginx-demo

# Inspect a single project as JSON
./bin/caractrl --output json get projects nginx-demo

apply

Create or update a resource from a YAML or JSON manifest. The kind field in the manifest determines which resource type is applied. Supported kinds: Node, Project.

./bin/caractrl apply -f <file>
./bin/caractrl apply -f -      # read from stdin

Flags

Flag	Description
`-f, --filename`	Path to the manifest file, or `-` to read from stdin. Required.

Examples

# Apply a project manifest
./bin/caractrl apply -f examples/nginx-project.yaml
# project/nginx-demo created

# Apply a node manifest
./bin/caractrl apply -f node.yaml
# node/edge-node-01 created

# Apply from stdin
cat project.yaml | ./bin/caractrl apply -f -

delete node

Remove a node from the control plane by name.

./bin/caractrl delete node <name>

Example

./bin/caractrl delete node worker-03
# node "worker-03" deleted

delete project

Delete a project by name. The agent on the assigned node tears down all containers belonging to the project. If deletion is already in progress, the command reports that the project is being deleted.

./bin/caractrl delete project <name>

Example

./bin/caractrl delete project nginx-demo
# project "nginx-demo" deleted

port-forward

Forward a local TCP port to a container port on a remote node via the agent’s WebSocket tunnel. This works similarly to kubectl port-forward.

./bin/caractrl port-forward <project>/<service> [LOCAL_PORT:]REMOTE_PORT [--node <host:port>]

Arguments

Argument	Description
`<project>/<service>`	Target project and service name, separated by `/`.
`[LOCAL_PORT:]REMOTE_PORT`	Port mapping. Omit `LOCAL_PORT` to use the same port number locally and remotely.

Flags

Flag	Description
`--node`	Agent address (`host:port`). When omitted, `caractrl` resolves the agent address automatically from `cara-server` using the project’s `nodeRef`.

Examples

# Forward local port 5432 to the "db" service's port 5432 in project "my-app"
./bin/caractrl port-forward my-app/db 5432

# Forward local port 15432 to remote port 5432
./bin/caractrl port-forward my-app/db 15432:5432

# Specify the agent address explicitly
./bin/caractrl port-forward my-app/db 5432 --node 192.168.1.100:9090

Press Ctrl+C to stop forwarding and close the tunnel.

Automatic agent resolution requires the project to be in Running or Scheduled phase so that a nodeRef is set. If the project has not been scheduled yet, use --node to specify the agent address directly.

Get Started

Core Concepts

Manifests

Configuration

Guides

Global flags

Output format examples

Subcommands

version

get nodes

get projects

apply

delete node

delete project

port-forward

​Global flags

​Output format examples

​Subcommands

​version

​get nodes

​get projects

​apply

​delete node

​delete project

​port-forward

Global flags

Output format examples

Subcommands

version

get nodes

get projects

apply

delete node

delete project

port-forward