CLI Reference¶

Makefile Targets¶

Run make help to see all available targets.

Stack Management¶

Target	Description
`make setup`	Install local deps and create `.env` files from examples
`make up`	Start the full local stack (`docker compose up -d --build`)
`make down`	Stop the full local stack
`make restart`	Stop and restart the full stack
`make logs`	Tail logs for all services. Use `make logs svc=controller` for a specific service
`make ps`	Show Docker Compose service status

Database¶

Target	Description
`make migrate`	Run Django migrations in the controller container
`make seed`	Seed demo data and default users (runs migrate first)

Controller¶

Target	Description
`make controller-shell`	Open a bash shell in the controller container
`make controller-test`	Run controller tests inside the container
`make controller-format`	Format controller code locally with Ruff
`make controller-lint`	Lint controller code locally with Ruff

Dispatcher¶

Target	Description
`make dispatcher-shell`	Open a shell in the dispatcher container
`make dispatcher-test`	Run dispatcher tests against the root Postgres
`make dispatcher-format`	Format dispatcher code locally with gofmt
`make dispatcher-lint`	Lint dispatcher code locally with golangci-lint

Testing¶

Target	Description
`make test`	Run the default test suite (controller + dispatcher)
`make test-all`	Run both controller and dispatcher tests
`make test-integration`	Run full dispatch loop integration test (requires running stack)

Code Quality¶

Target	Description
`make format`	Run both formatters (Ruff + gofmt)
`make lint`	Run both linters (Ruff + golangci-lint)

Agent Images¶

Target	Parameters	Description
`make agent-build`	`TIER=terminal RUNTIME=claude`	Build a specific agent image
`make agent-build-all`	`TIER=terminal`	Build all runtime variants for a tier
`make agent-push`	`TIER=terminal RUNTIME=claude REGISTRY=localhost:5000`	Push an agent image to registry
`make agent-test`	--	Build and run the test agent

k3d Local Cluster¶

Target	Description
`make k3d-up`	Create k3d cluster with local registry at localhost:5000
`make k3d-down`	Delete the k3d cluster and registry
`make k3d-status`	Show k3d cluster status

Django manage.py Commands¶

Run inside the controller container or via make controller-shell.

Built-in¶

python manage.py migrate          # Apply database migrations
python manage.py createsuperuser  # Create admin user
python manage.py collectstatic    # Collect static files for production
python manage.py showmigrations   # List all migrations and their status
python manage.py dbshell          # Open a database shell
python manage.py shell            # Open a Django Python shell

Custom¶

python manage.py seed             # Seed demo data (admin user, sample records)

Dispatcher Go Commands¶

Build¶

cd dispatcher
go build -o api ./cmd/api

Run¶

cd dispatcher
go run ./cmd/api

Test¶

cd dispatcher
DATABASE_URL=postgres://postgres:postgres@localhost:5432/kohakku-dispatcher?sslmode=disable \
  go test ./...

Lint¶

cd dispatcher
golangci-lint run ./...

Docker Compose¶

The root docker-compose.yml defines the full local stack.

docker compose up -d --build           # Start all services
docker compose down                    # Stop all services
docker compose down -v                 # Stop and delete volumes (data loss)
docker compose logs -f controller      # Follow controller logs
docker compose exec controller bash    # Shell into controller
docker compose exec redis redis-cli    # Redis CLI
docker compose ps                      # Service status

k3d / kubectl¶

# Create cluster
k3d cluster create kohakku --registry-create kohakku-registry:5000

# Verify
kubectl get nodes --context k3d-kohakku

# Push an image to local registry
docker push localhost:5000/kohakku-agents:terminal-claude-latest

# Delete cluster
k3d cluster delete kohakku

MinIO Client (mc)¶

# Configure alias for local MinIO
mc alias set local http://localhost:9000 minioadmin minioadmin

# List objects
mc ls local/kohakku/

# Mirror to backup
mc mirror local/kohakku s3/kohakku-backup