Getting Started with DevCLI

A comprehensive guide to get you up and running with devcli in minutes.

What is devcli?

devcli is a powerful process management tool that helps you:

Manage processes through a centralized JSON configuration
Auto-start dependencies in the correct order
Run in multiple environments (local, Docker, Kubernetes)
Monitor health and automatically restart crashed processes
View logs in a beautiful terminal UI
Track metrics for all your running processes

Perfect for microservices development, monorepo projects, and complex local development setups.

Installation

Prerequisites

macOS (10.15+) or Linux (Ubuntu 20.04+, or equivalent)
No other dependencies required!

Quick Install (Recommended)

Installs the latest devcli and its pm-daemon background daemon into ~/.devcli/bin:

curl -fsSL https://raw.githubusercontent.com/xDelph/devcli/develop/install.sh | sh

Homebrew

brew tap xDelph/devcli
brew install devcli

Manual Installation

macOS (Apple Silicon M1/M2/M3):

curl -L https://github.com/xDelph/devcli/releases/latest/download/devcli-aarch64-apple-darwin.tar.gz | tar xz
sudo mv devcli pm-daemon /usr/local/bin/
devcli --version

macOS (Intel):

curl -L https://github.com/xDelph/devcli/releases/latest/download/devcli-x86_64-apple-darwin.tar.gz | tar xz
sudo mv devcli pm-daemon /usr/local/bin/
devcli --version

Linux (x64):

curl -L https://github.com/xDelph/devcli/releases/latest/download/devcli-x86_64-unknown-linux-gnu.tar.gz | tar xz
sudo mv devcli pm-daemon /usr/local/bin/
devcli --version

Build from Source

git clone https://github.com/xDelph/devcli.git
cd devcli
cargo build --release
sudo cp target/release/devcli target/release/pm-daemon /usr/local/bin/

Quick Start (5 minutes)

1. Initialize Configuration

# Create default config file at ~/.devcli/config.json
devcli config init

# Verify it was created
cat ~/.devcli/config.json

2. Auto-Detect Your First App

Navigate to any Node.js, Docker, or Kubernetes project:

cd ~/my-awesome-api
devcli auto-add

# This detects your app type and adds it to config
# ✓ Detected: nodejs app "my-awesome-api"
# ✓ Found commands: start, test, build
# ✓ Added to config

3. Start Your App

# Start in local environment (default)
devcli start my-awesome-api

# Or start in Docker
devcli start my-awesome-api --env docker

# Or with dependencies auto-started
devcli start frontend  # Also starts api, database, etc.

4. Check Status

devcli status

# Output:
# ┌─────────────────────────────────────────┐
# │ Running Processes                       │
# ├─────────────────────────────────────────┤
# │ my-awesome-api (PID 12345) ✓ healthy   │
# │   Uptime: 2m 34s                        │
# │   Project: awesome-project              │
# └─────────────────────────────────────────┘

5. View Logs

# Launch interactive TUI to view logs
devcli ui

# Or get current status
devcli status my-awesome-api

6. Stop

# Stop specific app
devcli stop my-awesome-api

# Stop all apps
devcli stop --all

Core Concepts

Configuration File

Located at ~/.devcli/config.json, this file defines:

{
  "projects": {
    "awesome-project": {
      "apps": {
        "api": {
          "type": "nodejs",
          "path": "~/code/awesome-project/api",
          "commands": {
            "local": {
              "start": "npm run dev",
              "test": "npm test"
            },
            "docker": {
              "start": "docker compose up api"
            }
          },
          "dependencies": [
            "database"
          ],
          "health_check": {
            "http": {
              "url": "http://localhost:3000/health",
              "expected_status": 200
            }
          },
          "restart_policy": {
            "max_restarts": 5,
            "restart_window_secs": 300
          }
        }
      }
    }
  }
}

Projects

A project is a logical grouping of related apps (e.g., your microservices).

Apps

An app is a single process/service you want to manage. Each app has:

Commands for different environments (local, docker, k8s)
Dependencies on other apps
Health checks to monitor status
Restart policies for automatic recovery

Environments

Run the same app in different environments:

local: Native execution (npm, cargo, go, etc.)
docker: Docker Compose or standalone containers
k8s: Kubernetes manifests
orbstack: OrbStack optimized commands

Common Workflows

Workflow 1: Starting a Full Stack

# Start frontend (also starts api, database, redis)
devcli start frontend

# Check what's running
devcli status --deps

# View logs in TUI
devcli ui

Workflow 2: Development with Hot Reload

# Start in local mode with hot reload
devcli start api --env local

# Make code changes... app reloads automatically

# Run tests in separate terminal
devcli run api test

Workflow 3: Docker Development

# Start everything in Docker
devcli start --all --env docker

# Health checks ensure containers are ready
devcli health-check api

# View container logs
devcli ui

Workflow 4: Managing Long-Running Services

# Start with monitor daemon (auto-restarts on crash)
devcli start database

# Monitor starts automatically in background
# Check metrics
devcli metrics

# View metrics API
curl http://localhost:9090/metrics | jq

Next Steps

Explore Commands

# List all apps in config
devcli config list

# Show details of an app
devcli config show api

# Run custom command
devcli run api build:production

# Check health manually
devcli health-check api

Configure Health Checks

Add health checks to detect when apps need restart:

{
  "health_check": {
    "http": {
      "url": "http://localhost:3000/health",
      "timeout_secs": 5,
      "expected_status": 200
    }
  }
}

Set Up Restart Policies

Automatically restart crashed processes:

{
  "restart_policy": {
    "max_restarts": 5,
    "restart_window_secs": 300,
    "backoff_secs": 5
  }
}

Add Environment Files

Manage environment-specific variables:

# Add .env file for different stages
devcli env add api --stage qa --context docker --file .env.qa
devcli env add api --stage prod --context k8s --file .env.prod

# List env files
devcli env list api

# Start with specific stage
devcli start api --stage qa

Set Preferences

# Set default environment
devcli pref set default-env docker

# Enable auto-start dependencies
devcli pref set auto-start-deps true

# View current preferences
devcli pref show

Detailed Guides

Configuration Reference - Complete config file documentation
Commands Reference - All CLI commands with examples
Advanced Features - Health checks, metrics, logging
Troubleshooting - Common issues and solutions

Tips & Tricks

Tip 1: Use Tab Completion

# Install completion (bash example)
devcli --generate-completion bash > /etc/bash_completion.d/devcli

Tip 2: Filter Logs

# Set log level
RUST_LOG=debug devcli start api

# View structured JSON logs
tail -f ~/.devcli/logs/devcli.$(date +%Y-%m-%d).json | jq

Tip 3: Quick Status Check

# Add alias to your shell
alias dc='devcli'
alias dcs='devcli status'
alias dcl='devcli ui'

# Now use shortcuts
dcs
dcl

Tip 4: Multiple Environments

# Dev environment
devcli start api --env local

# Test environment (Docker)
devcli start api --env docker --stage qa

# Production simulation (K8s)
devcli start api --env k8s --stage preprod

Getting Help

# General help
devcli --help

# Command-specific help
devcli start --help
devcli config --help

# Check version
devcli --version

What’s Next?

Now that you have the basics:

Explore the TUI: devcli ui for beautiful log viewing
Set up health checks: Automatically detect crashes
Configure dependencies: Start services in order
View metrics: devcli metrics for insights
Customize config: Add all your projects

Happy process managing! 🚀