Skip to content

lerim up / down / logs

Docker container lifecycle commands for starting, stopping, and monitoring Lerim.

Overview

These host-only commands manage the Docker container that runs lerim serve (daemon + JSON API).

Host-only commands

These commands run on the host machine. They do not require a running Lerim server.

Syntax

lerim up [--build] [--no-build]
lerim down
lerim logs [--follow]

Commands

lerim up

Start Lerim as a Docker service:

lerim up                    # start Lerim (pull GHCR image)
lerim up --build            # build and recreate from the local Dockerfile
lerim up --no-build         # reuse an existing local-build image

This reads ~/.lerim/config.toml, generates a docker-compose.yml in ~/.lerim/, and runs docker compose up -d.

By default the compose file references the pre-built GHCR image (ghcr.io/lerim-dev/lerim) tagged with the current package version. Use --build to build from the local Dockerfile, tag it as lerim-lerim:local, and force-recreate the container. After a successful local build, use --no-build to restart from the existing local image without rebuilding.

After start, the CLI waits for GET /api/health to return 200 OK before reporting success.

Local builds use a cache-aware Dockerfile: third-party dependencies install from uv.lock before src/ is copied, so normal source edits only reinstall the Lerim package layer. Docker compose startup has a default timeout of 1200 seconds; override it with LERIM_DOCKER_TIMEOUT_SECONDS for unusually slow machines or networks.

lerim down

Stop the Docker container:

lerim down

lerim logs

View local log entries from dated JSONL files under ~/.lerim/logs/YYYY/MM/DD/ (last 50 by default). If no log file exists yet, the command prints an empty-state message and exits successfully.

lerim logs                      # show recent logs
lerim logs --follow             # tail logs continuously
lerim logs --level error        # filter by level
lerim logs --since 2h           # entries from the last 2 hours
lerim logs --json               # raw JSONL output

Parameters

--build boolean default: off

Build from local Dockerfile instead of pulling the GHCR image.

--no-build boolean default: off

Reuse the existing local-build image instead of rebuilding it.

--follow, -f boolean default: off

Live tail: watch for new log lines and print as they appear.

--level string

Filter by log level (case-insensitive). E.g. error, warning, info.

--since string

Show entries from the last N hours/minutes/days. Format: 1h, 30m, 2d.

--json boolean default: off

Output raw JSONL lines instead of formatted text.

Examples

# Start the service
lerim up

# Check it's running
lerim status

# View logs
lerim logs --follow

# Stop when done
lerim down

Notes

  • The container runs lerim serve which provides the daemon loop and JSON API
  • http://localhost:8765/api/health is the local health endpoint
  • http://localhost:8765/ serves a small local stub/diagnostic page
  • Docker restart policy is "no" — the container does not auto-restart after reboots