Commands Reference

Complete reference for all devcli CLI commands.

Process Management - start, stop, restart, run, status
Monitoring - monitor, health-check, metrics, ui
Configuration - config commands
Environment Management - env commands
Preferences - pref commands
Utilities - auto-add

Process Management

`start`

Start one or more applications.

Usage:

devcli start <app-names>... [OPTIONS]

Arguments:

<app-names> - One or more app names to start

Options:

-p, --project <NAME> - Project name (if app name is ambiguous)
-e, --env <ENV> - Environment: local, docker, k8s (overrides preference)
--skip-deps - Skip starting dependencies
-s, --stage <STAGE> - Deployment stage: dev, qa, prod, etc.

Examples:

# Start single app
devcli start api

# Start multiple apps
devcli start api worker frontend

# Start in Docker environment
devcli start api --env docker

# Start with dependencies skipped
devcli start api --skip-deps

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

# Start with project disambiguation
devcli start api --project awesome-project

Behavior:

Auto-starts dependencies (unless --skip-deps)
Spawns process in background
Starts monitor daemon automatically
Tracks process state in ~/.devcli/state.json
Logs to ~/.devcli/logs/<project>_<app>_<date>.log

`stop`

Stop one or more running applications.

Usage:

devcli stop [app-name] [OPTIONS]

Arguments:

[app-name] - Optional app name (if not using —all or —project)

Options:

-p, --project <NAME> - Stop all apps in project
--all - Stop all running processes
--force - Force kill (SIGKILL instead of SIGTERM)

Examples:

# Stop specific app
devcli stop api

# Stop all apps in project
devcli stop --project awesome-project

# Stop everything
devcli stop --all

# Force kill
devcli stop api --force

Behavior:

Sends SIGTERM by default (graceful shutdown)
Waits 5 seconds for graceful exit
Uses SIGKILL if —force or after timeout
Removes from state tracking
Monitor daemon exits when no processes remain

`restart`

Restart a running application with same configuration.

Usage:

devcli restart <app-name> [OPTIONS]

Arguments:

<app-name> - App name to restart

Options:

-p, --project <NAME> - Project name
-e, --env <ENV> - Environment (can change from current)
--skip-deps - Skip restarting dependencies

Examples:

# Restart app
devcli restart api

# Restart in different environment
devcli restart api --env docker

# Restart without dependencies
devcli restart api --skip-deps

`run`

Run a specific command variant for an app.

Usage:

devcli run <app-name> <command-variant> [OPTIONS]

Arguments:

<app-name> - App name
<command-variant> - Command variant (e.g., test, build:production)

Options:

-p, --project <NAME> - Project name
-e, --env <ENV> - Environment
--skip-deps - Skip dependencies

Examples:

# Run tests
devcli run api test

# Run production build
devcli run api build:production

# Run in Docker
devcli run api test --env docker

# Run specific variant
devcli run api build:staging

`status`

Show status of running processes.

Usage:

devcli status [app-name] [OPTIONS]

Arguments:

[app-name] - Optional app name to filter

Options:

-p, --project <NAME> - Filter by project
--deps - Show dependency status

Examples:

# Show all running processes
devcli status

# Show specific app
devcli status api

# Show project apps
devcli status --project awesome-project

# Show with dependencies
devcli status --deps

Output Example:

┌─────────────────────────────────────────────┐
│ Running Processes                           │
├─────────────────────────────────────────────┤
│ api (PID 12345) ✓ healthy                  │
│   Project: awesome-project                  │
│   Environment: local                        │
│   Uptime: 1h 23m 45s                       │
│   Restarts: 0                              │
│   Health: ✓ http://localhost:3000/health  │
└─────────────────────────────────────────────┘

Monitoring

`monitor`

Run health monitoring daemon (usually auto-started).

Usage:

devcli monitor [OPTIONS]

Options:

--daemon - Run as background daemon

Examples:

# Run daemon (internal use, auto-started by 'start')
devcli monitor --daemon

# Manual cleanup run (without daemon)
devcli monitor

Behavior:

Monitors all running processes
Performs health checks every 3 seconds
Auto-restarts crashed processes (with restart_policy)
Tracks metrics
Exposes metrics API on localhost:9090
Exits automatically when no processes remain

`health-check`

Manually check health of a running app.

Usage:

devcli health-check <app-name> [OPTIONS]

Arguments:

<app-name> - App name to check

Options:

-e, --env <ENV> - Environment

Examples:

# Check health
devcli health-check api

# Check in Docker
devcli health-check api --env docker

Output Example:

Health Check: api
✓ HTTP check passed
  URL: http://localhost:3000/health
  Status: 200 OK
  Response time: 45ms

`metrics`

Display metrics from the monitor daemon.

Usage:

devcli metrics

Output Example:

=== Process Metrics ===
Total Processes:       3
  Running:             3 ●
  Stopped:             0 ○

Total Restarts:        5
Restarts (last hour):  2
Health Check Success:  98.5%

Exit Code Distribution:
  Exit 0: 3 times ✓
  Exit 1: 2 times ✗

=== System Metrics ===
Monitor Uptime:        3600 seconds (60 minutes)
Loop Iterations:       1200
DevCLI Version:        0.1.0
Apps Configured:       12

=== Performance Metrics ===
Avg Startup Time:      450.23 ms
Avg Health Check:      42.15 ms
Avg Restart Time:      1023.45 ms

HTTP API:

# Raw JSON via API
curl http://localhost:9090/metrics | jq

`ui`

Launch interactive TUI for viewing logs.

Usage:

devcli ui

Features:

View logs for all running processes
Real-time log streaming
Syntax highlighting
Multi-pane view
Keyboard navigation
ANSI color support

Keyboard Shortcuts:

↑/↓ or j/k - Scroll
Tab - Switch between apps
g/G - Jump to top/bottom
h - Help overlay
q - Quit

Configuration

`config init`

Initialize a new configuration file.

Usage:

devcli config init

Behavior:

Creates ~/.devcli/config.yaml
Starts with empty projects
Won’t overwrite existing file

`config validate`

Validate the configuration file.

Usage:

devcli config validate

Checks:

YAML syntax
Required fields
Dependency existence
Circular dependencies
Health check format
Command structure

`config list`

List all projects and apps.

Usage:

devcli config list [OPTIONS]

Options:

-p, --project <NAME> - Filter by project
--apps-only - Show only app names

Examples:

# List everything
devcli config list

# List specific project
devcli config list --project awesome-project

# List just app names
devcli config list --apps-only

`config show`

Show detailed configuration for an app.

Usage:

devcli config show <app-name> [OPTIONS]

Arguments:

<app-name> - App name

Options:

-p, --project <NAME> - Project name

Examples:

devcli config show api
devcli config show api --project awesome-project

`config edit`

Open configuration file in editor.

Usage:

devcli config edit

Behavior:

Opens ~/.devcli/config.yaml in $EDITOR
Falls back to vim if $EDITOR not set

`config add-command`

Add a command to an app (interactive).

Usage:

devcli config add-command [app-name] [environment] [command-name] [command-value] [OPTIONS]

Examples:

# Interactive (prompts for all fields)
devcli config add-command

# Partial (prompts for missing)
devcli config add-command api

# Full command
devcli config add-command api local build "npm run build"

`config remove-command`

Remove a command from an app (interactive).

Usage:

devcli config remove-command [app-name] [environment] [command-name] [OPTIONS]

`config set-default`

Set the default command for an environment.

Usage:

devcli config set-default [app-name] [environment] [command-name] [OPTIONS]

`config list-commands`

List all commands for an app.

Usage:

devcli config list-commands [app-name] [OPTIONS]

Options:

-p, --project <NAME> - Project name
-e, --env <ENV> - Filter by environment

`config edit-command`

Edit an existing command (interactive).

Usage:

devcli config edit-command [app-name] [environment] [command-name] [OPTIONS]

Environment Management

`env add`

Add an environment file mapping.

Usage:

devcli env add <app-name> --stage <STAGE> --context <CONTEXT> --file <FILE>

Options:

--stage <STAGE> - Stage name (dev, qa, prod, etc.)
--context <CONTEXT> - Context (local, docker, k8s)
--file <FILE> - Path to env file (relative to app path)

Examples:

devcli env add api --stage dev --context local --file .env.dev
devcli env add api --stage qa --context docker --file .env.qa

`env remove`

Remove an environment file mapping.

Usage:

devcli env remove <app-name> --stage <STAGE> [--context <CONTEXT>]

Examples:

# Remove specific context
devcli env remove api --stage dev --context local

# Remove entire stage
devcli env remove api --stage dev

`env list`

List environment files for an app.

Usage:

devcli env list <app-name>

Examples:

devcli env list api

Output Example:

Environment Files for api:

dev:
  local: .env.dev
  docker: .env.docker.dev

qa:
  docker: .env.qa
  k8s: k8s/qa/env.yaml

prod:
  k8s: k8s/prod/env.yaml

`env set-default`

Set default stage for a context.

Usage:

devcli env set-default <app-name> --context <CONTEXT> --stage <STAGE>

Examples:

devcli env set-default api --context docker --stage dev

Preferences

`pref set`

Set a preference value.

Usage:

devcli pref set <key> <value>

Available Keys:

default-env - Default environment (local, docker, k8s)
auto-start-deps - Auto-start dependencies (true, false)
docker-platform - Docker platform (linux/amd64, linux/arm64)

Examples:

devcli pref set default-env docker
devcli pref set auto-start-deps false
devcli pref set docker-platform linux/arm64

`pref show`

Show current preferences.

Usage:

devcli pref show

Output Example:

Current Preferences:
  default-env:       local
  auto-start-deps:   true
  docker-platform:   linux/amd64

`pref reset`

Reset preferences to defaults.

Usage:

devcli pref reset

Utilities

`auto-add`

Auto-detect app and add to configuration.

Usage:

devcli auto-add [OPTIONS]

Options:

--path <PATH> - Path to detect (defaults to current directory)

Examples:

# Detect current directory
cd ~/my-app
devcli auto-add

# Detect specific path
devcli auto-add --path ~/code/another-app

Supported Detection:

Node.js (package.json)
Nx Monorepo (nx.json)
Docker (Dockerfile, docker-compose.yml)
Kubernetes (k8s/*.yaml)
Rust (Cargo.toml)
Go (go.mod)
Python (setup.py, pyproject.toml)

Global Options

Available for all commands:

-h, --help - Show help
-V, --version - Show version

Examples:

devcli --help
devcli start --help
devcli --version

Environment Variables

`RUST_LOG`

Control logging verbosity:

# Debug logs
RUST_LOG=debug devcli start api

# Trace (very verbose)
RUST_LOG=trace devcli start api

# Module-specific
RUST_LOG=devcli_core::commands::start=debug devcli start api

`DEVCLI_CONFIG`

Override config file location:

export DEVCLI_CONFIG=~/my-config.yaml
devcli start api

Exit Codes

0 - Success
1 - General error
Other codes preserved from child processes

Commands Reference

Table of Contents

Process Management

start

stop

restart

run

status

Monitoring

monitor

health-check

metrics

ui

Configuration

config init

config validate

config list

config show

config edit

config add-command

config remove-command

config set-default

config list-commands

config edit-command

Environment Management

env add

env remove

env list

env set-default

Preferences

pref set

pref show

pref reset

Utilities

auto-add

Global Options

Environment Variables

RUST_LOG

DEVCLI_CONFIG

Exit Codes

See Also

`start`

`stop`

`restart`

`run`

`status`

`monitor`

`health-check`

`metrics`

`ui`

`config init`

`config validate`

`config list`

`config show`

`config edit`

`config add-command`

`config remove-command`

`config set-default`

`config list-commands`

`config edit-command`

`env add`

`env remove`

`env list`

`env set-default`

`pref set`

`pref show`

`pref reset`

`auto-add`

`RUST_LOG`

`DEVCLI_CONFIG`