deven

deven is a Rust CLI that boots a full local development environment from one YAML file. It manages setup tasks, Docker containers, local services, readiness checks, logs, and runtime state.

Why

Local dev stacks are often split between Docker infrastructure and app processes running directly on your machine. That usually leads to ad-hoc scripts, manual startup order, and inconsistent stop/restart behavior across a team.

deven gives you one repeatable workflow: define your stack once, start it in dependency order, wait for readiness, and manage logs/state from a single CLI.

What It Does

• Starts containers and services in dependency order
• Runs one-time setup tasks before long-running workloads
• Waits for readiness (port checks and/or command checks)
• Aggregates logs from local services and Docker containers
• Stores project-local runtime state in .deven/
• Supports profile-based subsets of your environment
• Forwards unknown subcommands to deven-<name> plugins

Prerequisites

• macOS or Linux
• Rust toolchain (cargo)
• Docker CLI plus a running Docker daemon
• POSIX shell (sh) on PATH

Installation

Run from source:

cargo run -- --help

Install locally:

cargo install --path .
deven --help

Build a release binary:

cargo build --release
./target/release/deven --help

Quick Start

1. Create deven.yaml in your project root.

env:
  APP_ENV: development

tasks:
  migrate:
    run: echo "running migrations"

containers:
  postgres:
    image: postgres:15
    ports: ["5432:5432"]
    readiness:
      ports: [5432]
      timeout_secs: 30

services:
  api:
    run: python3 -m http.server 8080
    depends_on: [postgres]
    env:
      PORT: "8080"
    readiness:
      ports: [8080]

2. Start everything.

deven up --detach

3. Check status and logs.

deven status
deven logs --tail 200

4. Stop or reset.

deven stop
deven reset --yes

CLI

Global flag:

• --project-dir <path>: project directory to run against (default .)

Commands:

• deven up [--profile <name>] [--detach]
• deven stop
• deven run <service>
• deven restart <name>
• deven logs [--service <name>] [--tail <n>] [--no-follow]
• deven status
• deven reset --yes

Notes:

• deven up always starts from a clean tracked state by calling stop first.
• deven run <service> runs one service in the foreground.
• deven logs follows logs by default; use --no-follow for snapshot output.

Config File

Config discovery order:

1. deven.yaml
2. deven.yml

Top-level keys:

• env: global env vars merged into every task/service/container
• tasks: one-time commands executed before containers and services
• containers: Docker workloads
• services: long-running local processes
• profiles: optional filtered subsets of tasks/containers/services
• watch: optional file watcher that triggers deven restart <service>

Environment merge precedence:

1. Host process environment
2. Top-level env
3. Per-task/per-service/per-container env

Service Example

services:
  api:
    run: cargo run -p api
    cwd: .
    env:
      PORT: "8080"
    depends_on: [postgres, redis]
    readiness:
      ports: [8080]
      command: curl -fsS http://127.0.0.1:8080/health
      timeout_secs: 30
      interval_ms: 500

Container Example

containers:
  redis:
    image: redis:7
    ports: ["6379:6379"]
    env:
      REDIS_PASSWORD: secret
    volumes:
      - "redis-data:/data"
    depends_on: [postgres]
    readiness:
      ports: [6379]

Task Example

tasks:
  migrate:
    run: cargo run -p migrate
    cwd: .
    env:
      DATABASE_URL: postgres://localhost:5432/app

Profile Example

profiles:
  minimal:
    services: [api]
    containers: [postgres]
    tasks: [migrate]

Watch Example

watch:
  paths: ["src", "config"]
  restart: ["api"]
  debounce_ms: 750

watch only runs when deven up is started without --detach.

Startup Flow (deven up)

1. Load config and apply profile (if set)
2. Stop previously tracked services and containers
3. Run all tasks
4. Start containers in dependency order
5. Start services in dependency-aware batches
6. Run readiness checks after each start
7. Save runtime state in .deven/state.json
8. Stream logs (unless --detach)
9. Start watcher (if configured and attached mode)

Plugins

Unknown subcommands are forwarded to executables named deven-<subcommand>.

Example:

deven doctor --verbose

Runs:

deven-doctor --verbose

Runtime Files

deven keeps project-local runtime data in:

• .deven/state.json
• .deven/logs/*.log

These files drive status, logs, stop, and restart.

Development

Run checks before opening a PR:

cargo fmt --all -- --check
cargo clippy --all-targets --all-features
cargo test --all-targets --all-features

CI runs the same checks on Ubuntu and macOS.

Contributing

1. Fork the repository
2. Create a feature branch
3. Add tests when applicable
4. Run formatting, linting, and tests
5. Open a pull request with a clear description

For bugs or feature requests, open a GitHub issue.

License

Licensed under MIT. See LICENSE.