CLI Reference

mt is the operator-facing entry point to Mentat. It talks to mentat-server over HTTP and is designed to cover the common lifecycle of a private workload platform: deploy, inspect, scale, update, and recover.

global options
mt [--server <URL>] <command>

Options:
  --server <SERVER>  Mentat server address [default: http://127.0.0.1:4646]
  -h, --help         Print help

Core Commands

mt up <up.yaml>

Bring a Hull service up from a single YAML — bootstrap or update. Synthesises the container manifest, registers the service spec, generates the Caddy ingress block, runs the build, repacks the rootfs, pushes, extracts on host, and scales. Idempotent. No SSH required.

mt up up.yaml
mt --server https://www.getmentat.run up up.yaml

# up.yaml shape
name: stil-site
domain: stil.gitweave.run
aliases: [gitweave.run]
replicas: 2
build:
  cwd: ./
  cmd: stil run build
  output: dist
runtime:
  serve: static    # preset: static | node | argv
  port: 3007
  memory: 64M
  cpu: 0.5
  pids: 16
health: /

mt deploy <deploy.yaml>

Update content of an existing Hull service. Skips manifest write / spec register; just builds, repacks, pushes, extracts, bounces. Use when the service is already registered (mt up handled bootstrap).

mt deploy deploy.yaml

# deploy.yaml shape
service: stil-site
build:
  cwd: /path/to/landing
  cmd: stil run build
  output_dir: dist
target:
  www_path: /www
  preserve: [/www/releases]
replicas: 2

mt run <file.yaml>

Submit a workload definition file to the control plane. Low-level entry point for non-Hull drivers (Firecracker, Sandbox, Docker, Exec). Hull services usually go through mt up instead.

mt run services.yaml
mt run --server http://10.0.0.1:4646 production.yaml

mt status [job-id]

Inspect jobs and allocations. Use a job ID to drill into one deployment.

mt status
mt status abc123-def456

mt deploy-image <service> --image <tag>

Roll out a new image using the service's deployment strategy (legacy single-flag flow, kept for non-Hull services and CI scripts).

mt deploy-image api-gateway --image registry.example/api-gateway:v2
mt deploy-image streamforge --image streamforge:v2 --strategy canary

mt ps

Show all running workloads with live cgroups v2 metrics. Displays service name, driver, endpoints, RAM usage, CPU time, PIDs, and health status. Color-coded by driver type.

mt ps

SERVICE                DRIVER        EP   ADDRESS          RAM     CPU     PIDS   STATUS
streamforge-node1      firecracker   1    172.16.0.2:8080  256M    —       —      healthy
oxidestore-node1       firecracker   1    172.16.0.5:9000  256M    —       —      healthy
mentat-web             sandbox       1    127.0.0.1:3001   2/32M   12ms    3      healthy
nextjs-ssr             sandbox       1    127.0.0.1:3002   45/256M 890ms   8      healthy
api-jarvis             docker        1    172.17.0.3:5001  512M    —       —      healthy

mt scale <service> <count>

Change the target replica count for a service.

mt scale api-gateway 5
mt scale api-service 3

mt rollback <service>

Return a service to the previous deployable version.

mt rollback api-service

mt canary promote <service>

Promote an in-flight canary to the full rollout.

mt canary promote streamforge

mt canary abort <service>

Abort an in-flight canary and revert the change.

mt canary abort streamforge

mt nodes

List registered nodes and their available resources.

mt nodes

mt logs <service>

Inspect logs from a service. Use -f to follow.

mt logs api-gateway
mt logs api-gateway -f

Typical Operator Flow

# Start control plane and host agent
mentat-server --bind 0.0.0.0:4646
mentat-agent --kvm --server http://localhost:4646

# Submit a stack definition
mt run services.yaml

# Check what is running
mt status
mt nodes

# Change one service safely
mt deploy api-gateway --image registry.example/api-gateway:v2
mt rollback api-gateway

Observed Production Output

mt run services.yaml
$ mt run services.yaml
  scheduling 4 services...
  driver: firecracker  x2 services
  driver: exec         x1 services
  driver: docker       x1 services

  streamforge-broker x2  8ms   <- production traffic
  oxidestore        x1  6ms   <- S3 API live
  mentat-agent      x1  2ms
  api-jarvis        x1  380ms

  all services healthy
  firecracker + docker + exec  ·  private control plane

Interfaces

Terminal UI

mt lens --server your-host:4646

Desktop App

Mentat Desktop connects to the API over HTTPS for graphical monitoring and day-to-day operations. Use it when a team wants visibility without living entirely in the terminal.

Safe Change Management

# Canary first
mt deploy streamforge --image streamforge:v2 --strategy canary

# Evaluate, then decide
mt canary promote streamforge
# or: mt canary abort streamforge