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>
--server
string
default:"http://localhost:8080"
URL of the cara-server control plane. Override this when cara-server is not running on localhost.
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")'
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>]
# 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>]
| Flag | Description |
|---|
--phase | Filter by phase: Pending, Scheduled, Running, Failed, Terminating |
# 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
| Flag | Description |
|---|
-f, --filename | Path to the manifest file, or - to read from stdin. Required. |
# 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>
./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>
./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>]
| 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. |
| Flag | Description |
|---|
--node | Agent address (host:port). When omitted, caractrl resolves the agent address automatically from cara-server using the project’s nodeRef. |
# 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
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.
