Configuration Reference

Complete reference for the devcli configuration file (config.json).

Configuration File Location

DevCLI looks for configuration files in the following priority order:

Environment Variable: devcli_CONFIG_DIR (for testing/override)
Local Project Config: ./.devcli/config.json (current directory)
Global Config: ~/.devcli/config.json (home directory)

This allows you to have:

Global config at ~/.devcli/config.json for all your personal projects
Project-specific config at ./devcli/config.json for team projects or specific workflows

# Override for testing
export devcli_CONFIG_DIR=/tmp/test-config
devcli start api

# Or use local project config
cd ~/my-project
mkdir .devcli
# Create .devcli/config.json
devcli start api  # Uses ./devcli/config.json

Preferences File

Similarly, preferences are loaded from:

devcli_CONFIG_DIR/preferences.json (if env var set)
./.devcli/preferences.json (current directory)
~/.devcli/preferences.json (home directory)

File Structure

{
  "projects": {
    "project-name": {
      "apps": {
        "app-name": {
          "type": "nodejs",
          "path": "~/code/app-name",
          "commands": {}
        }
      }
    }
  }
}

Full Example

{
  "projects": {
    "awesome-monorepo": {
      "alternative_name": "ProjectA",
      "apps": {
        "database": {
          "type": "docker",
          "path": "~/code/awesome-monorepo/docker",
          "commands": {
            "local": {
              "start": "docker compose up postgres",
              "stop": "docker compose stop postgres"
            },
            "docker": {
              "start": "docker compose up postgres",
              "stop": "docker compose stop postgres"
            }
          },
          "health_check": {
            "tcp": {
              "host": "localhost",
              "port": 5432,
              "timeout_secs": 10
            }
          }
        },
        "api": {
          "type": "nodejs",
          "alternative_name": "Backend",
          "path": "~/code/awesome-monorepo/apps/api",
          "commands": {
            "local": {
              "default": "start",
              "start": "npm run dev",
              "test": "npm test",
              "build": "npm run build",
              "build:production": "npm run build:prod"
            },
            "docker": {
              "default": "start",
              "start": "docker compose up api",
              "build": "docker compose build api"
            },
            "k8s": {
              "default": "apply",
              "apply": "kubectl apply -f k8s/",
              "delete": "kubectl delete -f k8s/",
              "restart": "kubectl rollout restart deployment/api"
            }
          },
          "dependencies": [
            "database",
            "redis"
          ],
          "health_check": {
            "http": {
              "url": "http://localhost:3000/health",
              "expected_status": 200,
              "timeout_secs": 5
            }
          },
          "restart_policy": {
            "max_restarts": 5,
            "restart_window_secs": 300,
            "backoff_secs": 5
          },
          "env_files": {
            "dev": {
              "local": ".env.dev",
              "docker": ".env.docker.dev"
            },
            "qa": {
              "docker": ".env.qa",
              "k8s": "k8s/env/qa.yaml"
            },
            "prod": {
              "k8s": "k8s/env/prod.yaml"
            }
          }
        },
        "worker": {
          "type": "nodejs",
          "path": "~/code/awesome-monorepo/apps/worker",
          "commands": {
            "local": {
              "default": "start",
              "start": "npm run worker"
            },
            "docker": {
              "default": "start",
              "start": "docker compose up worker"
            }
          },
          "dependencies": [
            "database",
            "redis",
            "api"
          ],
          "restart_policy": {
            "max_restarts": 10,
            "restart_window_secs": 600
          }
        },
        "frontend": {
          "type": "nodejs",
          "path": "~/code/awesome-monorepo/apps/frontend",
          "commands": {
            "local": {
              "default": "start",
              "start": "npm run dev",
              "build": "npm run build",
              "preview": "npm run preview"
            },
            "docker": {
              "default": "start",
              "start": "docker compose up frontend"
            }
          },
          "dependencies": [
            "api"
          ],
          "health_check": {
            "http": {
              "url": "http://localhost:5173",
              "expected_status": 200
            }
          }
        }
      }
    }
  }
}

App Fields

Required Fields

`type`

Type: String Required: Yes Description: Type of application

Supported Values:

nodejs - Node.js applications
docker - Docker/Docker Compose
k8s - Kubernetes applications
rust - Rust applications
go - Go applications
python - Python applications
generic - Any other type

Example:

{
  "type": "nodejs"
}

`path`

Type: String (absolute or ~ expanded) Required: Yes Description: Working directory for the app

Example:

{
  "path": "~/code/my-project/apps/api"
}

`commands`

Type: Object Required: Yes Description: Commands to run in different environments

Structure:

{
  "commands": {
    "<environment>": {
      "<command-name>": "<command-string>",
      "default": "<default-command-name>"
    }
  }
}

Environments: local, docker, orbstack, k8s

Example:

{
  "commands": {
    "local": {
      "default": "start",
      "start": "npm run dev",
      "test": "npm test",
      "build": "npm run build",
      "build:production": "npm run build --mode production"
    },
    "docker": {
      "default": "start",
      "start": "docker compose up api",
      "build": "docker compose build api"
    }
  }
}

Optional Fields

`alternative_name`

Type: String Default: None Description: Privacy-friendly display name for screenshots or sharing Applies to: Both projects and apps

Features:

Displayed in TUI by default when present
Can be used in commands (start/stop/restart)
Shown as actualName(alternativeName) in terminal commands
Hides real names in screenshots and demonstrations

Example (Project):

{
  "projects": {
    "my-company-internal-project": {
      "alternative_name": "ProjectX",
      "apps": {
        "internal-api": {
          "alternative_name": "API"
        }
      }
    }
  }
}

Example (App):

{
  "apps": {
    "sensitive-app-name": {
      "alternative_name": "MyApp",
      "type": "nodejs",
      "path": "~/code/sensitive-app-name"
    }
  }
}

Usage:

# Start using alternative name
devcli start MyApp

# TUI displays "MyApp" instead of "sensitive-app-name"
devcli ui

# Config commands show both
devcli config show sensitive-app-name
# Output: App: sensitive-app-name(MyApp)
#         Project: my-company-internal-project(ProjectX)

Use Cases:

Recording screencasts without revealing internal names
Sharing configuration examples publicly
Presentations and demos
Training materials

`dependencies`

Type: Array of strings Default: [] Description: Apps that must be started before this app

Features:

Automatic dependency resolution
Transitive dependencies supported
Circular dependency detection
Can be disabled with --skip-deps

Example:

{
  "dependencies": [
    "database",
    "redis",
    "auth-service"
  ]
}

Behavior:

# Starting frontend also starts api and database
devcli start frontend
# → Starts: database → api → frontend

`health_check`

Type: Object Default: None Description: Health check configuration

Types: http, tcp, command

HTTP Health Check:

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

TCP Health Check:

{
  "health_check": {
    "tcp": {
      "host": "localhost",
      "port": 5432,
      "timeout_secs": 10
    }
  }
}

Command Health Check:

{
  "health_check": {
    "command": {
      "cmd": "curl -f http://localhost:3000/health",
      "timeout_secs": 5
    }
  }
}

Features:

Monitor daemon runs checks every 3 seconds
Tracks failure count
Triggers restart after 3 consecutive failures
Resets on successful check

`restart_policy`

Type: Object Default: None Description: Automatic restart configuration

Fields:

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

Behavior:

Restarts process on crash (non-zero exit code)
Exponential backoff: 5s, 10s, 20s, 40s, 80s…
Resets restart count after window expires
Stops restarting after max_restarts reached

Example:

{
  "restart_policy": {
    "max_restarts": 10,
    "restart_window_secs": 600,
    "backoff_secs": 3
  }
}

`env_files`

Type: Object Default: {} Description: Environment files for different stages

Structure:

{
  "env_files": {
    "<stage>": {
      "<context>": "<file-path>"
    }
  }
}

Stages: Any string (e.g., dev, qa, staging, prod) Contexts: local, docker, orbstack, k8s

Example:

{
  "env_files": {
    "dev": {
      "local": ".env.dev",
      "docker": ".env.docker.dev"
    },
    "qa": {
      "docker": ".env.qa",
      "k8s": "k8s/qa/env.yaml"
    },
    "prod": {
      "k8s": "k8s/prod/env.yaml",
      "default_context": "k8s"
    }
  }
}

Usage:

# Use dev stage (local context)
devcli start api --stage dev

# Use qa stage (docker context)
devcli start api --stage qa --env docker

File Paths:

Relative to app’s path directory
Absolute paths supported
~ expansion supported

Command Variants

Commands can have variants for different build targets, test suites, etc.

Syntax

{
  "commands": {
    "local": {
      "<command>": "<simple-command>",
      "<command>:<variant>": "<variant-command>"
    }
  }
}

Examples

Build Variants:

{
  "commands": {
    "local": {
      "build": "npm run build",
      "build:development": "npm run build --mode development",
      "build:production": "npm run build --mode production",
      "build:staging": "npm run build --mode staging"
    }
  }
}

Test Variants:

{
  "commands": {
    "local": {
      "test": "npm test",
      "test:unit": "npm run test:unit",
      "test:integration": "npm run test:integration",
      "test:e2e": "npm run test:e2e"
    }
  }
}

Docker Variants:

{
  "commands": {
    "docker": {
      "build": "docker compose build",
      "build:no-cache": "docker compose build --no-cache",
      "build:dev": "docker compose -f docker-compose.dev.yml build"
    }
  }
}

Usage

# Run specific variant
devcli run api build:production
devcli run api test:integration

# Default variant
devcli run api build

Default Commands

Each environment should have a default command:

{
  "commands": {
    "local": {
      "default": "start",
      "start": "npm run dev",
      "test": "npm test"
    }
  }
}

Used When:

devcli start api          # Uses 'default' → 'start'
devcli start api --env docker  # Uses docker's 'default'

App Types & Auto-Detection

devcli can auto-detect app types and generate commands:

Supported Auto-Detection

Type	Detection	Generated Commands
Node.js	`package.json`	start, test, build (from scripts)
Nx Monorepo	`nx.json`	Per-app targets
Docker	`Dockerfile`	build, run (single/multi-stage)
Docker Compose	`docker-compose.yml`	up, down, build
Kubernetes	`k8s/*.yaml`	apply, delete, restart
Rust	`Cargo.toml`	run, test, build, check
Go	`go.mod`	run, test, build
Python	`setup.py`/`pyproject.toml`	Based on project type

Auto-Add Command

cd ~/my-app
devcli auto-add

# Detects app type and adds to config
# You can edit ~/.devcli/config.json after

Environment Variables

In Commands

{
  "commands": {
    "local": {
      "start": "PORT=3000 npm run dev",
      "test": "NODE_ENV=test npm test"
    }
  }
}

Env Files (Docker)

Docker commands automatically inject --env-file:

{
  "commands": {
    "docker": {
      "start": "docker compose up api"
    }
  },
  "env_files": {
    "dev": {
      "docker": ".env.dev"
    }
  }
}

Becomes:

docker compose --env-file .env.dev up api

Env Files (Kubernetes)

K8s commands use env files as ConfigMaps/Secrets (manual setup required).

Validation

Validate Config

# Check for errors
devcli config validate

# Output:
# ✓ Config is valid
# ✓ 5 projects, 12 apps
# ✓ No circular dependencies

Common Errors

Missing required fields:

Error: App 'api' missing required field 'type'

Invalid dependencies:

Error: App 'api' depends on non-existent app 'database'

Circular dependencies:

Error: Circular dependency detected: api → worker → api

Best Practices

{
  "projects": {
    "main-app": {
      "apps": {
        "api": "...",
        "worker": "...",
        "frontend": "..."
      }
    },
    "monitoring": {
      "apps": {
        "prometheus": "...",
        "grafana": "..."
      }
    }
  }
}

2. Define Dependencies Explicitly

{
  "frontend": {
    "dependencies": [
      "api"
    ]
  },
  "api": {
    "dependencies": [
      "database",
      "redis"
    ]
  }
}

3. Add Health Checks for Critical Services

{
  "database": {
    "health_check": {
      "tcp": {
        "host": "localhost",
        "port": 5432
      }
    }
  },
  "api": {
    "health_check": {
      "http": {
        "url": "http://localhost:3000/health"
      }
    }
  }
}

4. Use Restart Policies for Long-Running Services

{
  "worker": {
    "restart_policy": {
      "max_restarts": 10,
      "restart_window_secs": 600
    }
  },
  "database": {
    "restart_policy": {
      "max_restarts": 3,
      "restart_window_secs": 300
    }
  }
}

5. Organize Env Files by Stage

apps/api/
├── .env.dev          # Local development
├── .env.docker.dev   # Docker development
├── .env.qa           # QA environment
└── .env.staging      # Staging environment

6. Use Command Variants for Build Targets

{
  "commands": {
    "local": {
      "build:dev": "npm run build:dev",
      "build:prod": "npm run build:prod",
      "build:analyze": "npm run build:analyze"
    }
  }
}

Configuration Management

Editing Config

# Open in $EDITOR
devcli config edit

# Or edit manually
vim ~/.devcli/config.json

Viewing Config

# List all projects and apps
devcli config list

# Show specific app
devcli config show api

# Filter by project
devcli config list --project awesome-monorepo

Adding/Removing Apps

Via Commands:

# Auto-detect and add
devcli auto-add

# Remove app
# (Manual edit required, or use config remove)

Manual Edit: Just edit ~/.devcli/config.json directly.

Backup Config

# Backup
cp ~/.devcli/config.json ~/.devcli/config.json.backup

# Restore
cp ~/.devcli/config.json.backup ~/.devcli/config.json

Advanced Configuration

Custom Dockerfile Paths

{
  "commands": {
    "docker": {
      "build": "docker build -f docker/Dockerfile.dev .",
      "start": "docker run -p 3000:3000 my-image"
    }
  }
}

Multiple Compose Files

{
  "commands": {
    "docker": {
      "start:dev": "docker compose -f docker-compose.yml -f docker-compose.dev.yml up",
      "start:prod": "docker compose -f docker-compose.yml -f docker-compose.prod.yml up"
    }
  }
}

Kubernetes Namespaces

{
  "commands": {
    "k8s": {
      "apply": "kubectl apply -f k8s/ -n my-namespace",
      "delete": "kubectl delete -f k8s/ -n my-namespace"
    }
  }
}

OrbStack Optimization

{
  "commands": {
    "orbstack": {
      "start": "docker compose up api"
    }
  }
}

Configuration Reference

Configuration File Location

Preferences File

File Structure

Full Example

App Fields

Required Fields

type

path

commands

Optional Fields

alternative_name

dependencies

health_check

restart_policy

env_files

Command Variants

Syntax

Examples

Usage

Default Commands

App Types & Auto-Detection

Supported Auto-Detection

Auto-Add Command

Environment Variables

In Commands

Env Files (Docker)

Env Files (Kubernetes)

Validation

Validate Config

Common Errors

Best Practices

1. Use Projects to Group Related Apps

2. Define Dependencies Explicitly

3. Add Health Checks for Critical Services

4. Use Restart Policies for Long-Running Services

5. Organize Env Files by Stage

6. Use Command Variants for Build Targets

Configuration Management

Editing Config

Viewing Config

Adding/Removing Apps

Backup Config

Advanced Configuration

Custom Dockerfile Paths

Multiple Compose Files

Kubernetes Namespaces

OrbStack Optimization

See Also

`type`

`path`

`commands`

`alternative_name`

`dependencies`

`health_check`

`restart_policy`

`env_files`