dev-cli

dev-cli is a local workspace orchestration tool for multi-service projects.

It starts services through a detached supervisor process, keeps live state on disk, exposes a terminal UI for manual control, and lets you inspect logs and basic git status from a single place.

What It Does

• Starts a full local environment from a declarative .devrc.yml.
• Expands service dependencies during the initial startup plan.
• Keeps a long-lived supervisor process per project so commands share the same runtime state.
• Opens a terminal UI to start, stop, restart, install, inspect, and manage services individually.
• Shows live workspace CPU/RAM metrics, per-service CPU/RAM usage, and git branch information when a service directory is a git repository.
• Stores per-service logs and opens them in the native terminal viewer from the UI.
• Opens a service directory in your editor or in an embedded terminal from the UI.

Requirements

• Node.js >= 24.19.0
• A Unix-like environment is recommended Current process management relies on ps and POSIX signals.
• git is only required for the branch-related UI actions (pull and checkout).

Installation

For local development, install dependencies, build the CLI, and link the dev command globally:

nvm use
yarn install
yarn build
npm link

After that, the command is available in your shell:

dev --help

If you change the CLI source code, run yarn build again to refresh dist.

How It Works

When you run dev up <project> or dev ui <project>, the CLI ensures a local supervisor process is running for that project. Commands such as status, ui, up, and down talk to that supervisor over a local socket and read the persisted state file when needed.

This keeps the UI responsive and allows service control commands to operate on the same source of truth.

Initialize a Workspace

Use dev init to create a .devrc.yml through an interactive wizard.

dev init

The wizard asks for the project name, groups, services, startup options, and service dependencies, then shows the final YAML before writing it.

Configuration

Create a .devrc.yml or .devrc.yaml in the workspace root (or .devrc.<project>.yml when the same directory holds more than one project):

project: amigo-workspace
session: amigo-workspace

hooks:
  beforeUp: echo "Preparing workspace"
  afterUp:
    - echo "Workspace requested"
  beforeDown: echo "Stopping workspace"

editor: code

groups:
  infra:
    services: [redis]
  api:
    services: [api]

services:
  redis:
    cwd: .
    command: docker run --rm -p 6379:6379 redis
    group: infra

  api:
    title: Main API
    cwd: ./api
    command: nvm use && yarn start:dev
    installCommand: yarn
    group: api
    port: 3000
    dependsOn: [redis]
    env:
      NODE_ENV: development

Config Reference

Root fields

• project: project identifier used by CLI commands.
• session: optional session name. If omitted, the project name is used.
• hooks.beforeUp: command or list of commands executed before up.
• hooks.afterUp: command or list of commands executed after up.
• hooks.beforeDown: command or list of commands executed before down.
• editor: optional editor command used by the UI editor action. Defaults to code.
• groups: named collections of services. These names can be used with --only.

Service fields

• title: optional display name used by the UI and by dev status. Defaults to the service key. The key stays the identifier for --only, logs, and every command.
• cwd: working directory for the service command.
• command: command used to run the service.
• installCommand: optional command used by the UI install action.
• group: group name the service belongs to.
• autostart: optional boolean, defaults to true.
• port: optional port, or list of ports, owned by the service.
• env: optional environment variables merged into the child process.
• dependsOn: optional list of service names required for the initial up plan.

Notes

• Config files are discovered only in the current workspace root, as .devrc.yml, .devrc.yaml or .devrc.<project>.yml / .devrc.<project>.yaml. Symbolic links pointing at a config file work too.
• The suffixed form lets one directory hold several projects. dev up <project> reads the candidates in alphabetical order and uses the first whose project field matches the argument, so the suffix is only a filename convention: the project field is what selects the config.
• project in the config must match the <project> argument passed to the CLI.
• Relative cwd values are resolved from the directory that contains the config file.
• ~/ and absolute cwd values are supported.
• Every service must belong to an existing group and must be listed in that group's services array.
• dependsOn is only used during dev up.
• dev up starts services in dependency phases.
• Stop and restart also work phase by phase (stop walks them in reverse), and every service inside the same phase is handled concurrently.
• After one dependency phase is started, the next dependent phase waits 5 seconds before starting.
• Services in the same dependency phase start together after that shared delay.
• --only accepts group names or service names.
• Group layout metadata is still accepted in the config for compatibility, but the built-in UI does not currently use it.
• Declared ports are released before a service starts and after down finishes: whatever is listening on them is sent SIGTERM, then SIGKILL if it survives 2 seconds. This clears orphan watchers that outlive the supervisor, so it also kills unrelated processes bound to those ports.
• Only ports declared with port are ever touched. Leave it out for services managed by Docker.
• Two services cannot declare the same port. The config is rejected, because a shared port would make one service kill the other when a dependency phase starts them together.
• Declared ports are shown in the UI PORT column on terminals wide enough for it.
• Hooks run in the workspace root using the current shell environment.
• Service commands and install commands run through the current shell from each service cwd.

Commands

dev up <project>

Starts the selected project environment through the supervisor and opens the terminal UI by default.

Examples:

dev up amigo-workspace
dev up amigo-workspace --only infra,api
dev up amigo-workspace --no-ui

Options:

• --only <targets>: comma-separated groups or service names.
• --no-ui: start the environment without opening the TUI.

Behavior:

• If no --only value is provided, all services with autostart: true are targeted.
• Dependencies are expanded for the initial startup plan.
• A fixed 5-second buffer is applied between dependency phases during dev up.
• beforeUp and afterUp hooks run around the up flow.

dev ui <project>

Ensures the supervisor is running and opens the terminal UI without starting services automatically.

dev ui amigo-workspace

dev status <project>

Prints a short service summary and the current service table.

dev status amigo-workspace

Behavior:

• If the supervisor is running, status is read from live supervisor state.
• Live status includes PID, uptime, memory, CPU, and log size columns.
• If the supervisor is not running, a config-based table is printed with services marked as stopped.

dev down <project>

Stops all services managed by the supervisor and shuts the supervisor down.

dev down amigo-workspace

Behavior:

• Runs the beforeDown hook before shutdown.
• Stops every managed service and removes the active supervisor state.
• Releases every port declared with port after the managed services exit.
• Prints one line per service stopped and per port released, then the final summary:

amigo-workspace: stopping services and releasing ports...
  ✓ Main API: Stopped
  ✓ Redis: Already stopped
  ✓ Main API: Released port 3000 (PID 4821)
amigo-workspace: stopped.

• A port line only shows up when something outside the supervisor tree was still holding the port.
• With no active session, it prints no active session to stop. and exits without doing anything.

dev init

Creates a .devrc.yml in the current directory through an interactive setup flow.

dev init

Behavior:

• Prompts for groups, services, commands, install commands, dependencies, and editor settings.
• Writes .devrc.yml when the flow is confirmed.

Terminal UI

The built-in UI lets you manage services individually after the supervisor is running.

The header shows the project name, running service count, and live CPU/RAM usage. Services are listed by their title when one is configured, falling back to the service key. The service list shows the current git branch for service directories that are git repositories, plus per-service memory and CPU usage when the terminal is wide enough. On wider terminals, the table also shows a TERM column when a service has an active embedded terminal session.

Navigation

• ↑/↓: move between services
• PageUp / PageDown: scroll logs
• Home / End: jump to top or bottom of the visible log pane
• q or Esc: exit the UI
• Shift+Q: exit the UI and stop the whole environment

Actions

• s or Enter: start the selected stopped service
• i: open a confirmation modal for installCommand on the selected stopped, failed, or running service
• k: kill the selected running service
• r: restart the selected running service, or recover a failed service by starting it again
• c: clear logs for the selected service when logs exist
• v: open the full service log in the native terminal viewer
• e: open the selected service directory in the configured editor
• t: open a full-screen embedded terminal for the selected service directory
• x: kill the embedded terminal for the selected service
• Shift+S: start all services
• Shift+K: kill all services (asks for confirmation)
• Shift+R: restart all services (asks for confirmation)
• Shift+Q: quit and down — asks for confirmation, then closes the UI and shuts the supervisor down, with the same effect as dev down <project> (beforeDown hook, port release, and the per-service shutdown lines printed in the terminal after the UI closes)
• ?: open a shortcut help modal with the full list of available keys
• Esc inside the embedded terminal: hide it and return to the UI; press t again to resume the same session for that service

The embedded terminal takes over the full TUI while it is visible. Hiding it restores the services and logs panes exactly where you left them.

If you try to exit the UI while one or more embedded terminal sessions are still running, the UI asks for confirmation before killing them.

Git actions

• p: open a confirmation modal for git pull --rebase
• d: open a confirmation modal with a branch input field and run git checkout

install, pull, and checkout clear the selected service log before running. When those actions target a running service, the supervisor stops the service first, runs the action, and restarts it after success without clearing the log again, so the command output remains visible in the log pane.

start always clears the selected service log before launching the service. restart stops the service, clears the log, and then starts it again.

Typical Workflow

dev up amigo-workspace
dev status amigo-workspace
dev ui amigo-workspace
dev down amigo-workspace

Common flow:

1. Define the workspace in .devrc.yml.
2. Run dev up <project> to start the environment.
3. Use the UI to inspect logs and control individual services.
4. Use dev status <project> when you want a quick non-interactive snapshot.
5. Run dev down <project> to stop everything cleanly.

Development

yarn install
yarn build
yarn test

yarn test builds the CLI and runs the Node test suite in test/*.test.mjs.

Project Scope

This project is focused on local development workflows, not production orchestration. It is designed for projects where a lightweight local supervisor and a terminal-first UI are enough to manage a multi-service workspace.