@productioneer/devctl v0.1.0

DevCtl - Development Service Manager

Fast, permission-free service manager for development workflows

DevCtl eliminates workflow interruptions by managing long-running processes in the background without permission prompts. Start your services once and let DevCtl handle the rest.

Features

• Fast execution (~1s per command)
• No permission prompts - runs silently in background
• Smart service naming - use short names when unambiguous
• Log buffering - captures up to 10,000 lines per service
• Automatic daemon management - starts on demand
• Support for npm/bun projects and arbitrary commands
• Path-based service organization
• Automatic Python venv activation - detects and activates virtual environments

Installation

From npm (recommended)

npm install -g @productioneer/devctl
# or
bun add -g @productioneer/devctl

From source

git clone https://github.com/productioneer/devctl.git
cd devctl
npm install
npm run build
npm link

Quick Start

# Start a service from package.json
devctl start dev
devctl start backend/dev
devctl start ./frontend/dev

# Run arbitrary commands
devctl run myserver -- python server.py
devctl run watcher -- npm run watch
devctl run backend -d ./api -- python -m uvicorn app:app

# Check status and logs
devctl status
devctl logs dev
devctl list

# Stop services
devctl stop dev
devctl restart dev
devctl killall

Commands

devctl start <service>

Starts a script from package.json. Supports path/service format:

• devctl start dev - starts 'dev' script in current directory
• devctl start backend/dev - starts 'dev' script in backend directory
• devctl start ./project/test - relative path support

devctl run <name> [options] -- <command...>

Runs any command as a managed service:

• devctl run server -- python app.py
• devctl run watcher -d ./src -- nodemon index.js

Important: Use -- before the command to prevent option parsing issues.

Options:

• -d, --dir <path> - Set working directory (default: current directory)

devctl stop <service>

Stops a running service. Uses SIGTERM with SIGKILL fallback after 5 seconds.

devctl restart <service>

Restarts a service with minimal downtime.

devctl logs <service>

Returns buffered logs since last read. Logs are cleared after reading.

devctl status [service]

Shows status of all services or a specific service with PID and uptime.

devctl list

Lists all running service names.

devctl killall

Kills all services started from current directory and subdirectories. Also cleans up daemon files.

Architecture

DevCtl uses a client-daemon architecture:

1. CLI Client (devctl) - Lightweight command interface
2. Daemon Process - Manages services, buffers logs, handles IPC
3. Unix Socket IPC - Fast communication between client and daemon

The daemon starts automatically on first command and runs in the background. State is stored in ~/.devctl/.

Service Naming

DevCtl supports flexible service naming:

# Full path/name format
devctl start frontend/dev
devctl stop frontend/dev

# Short name (when unambiguous)
devctl logs dev
devctl restart dev

# Handles ambiguity
devctl start project1/test
devctl start project2/test
devctl logs test  # Error: ambiguous
devctl logs project1/test  # Works

Python Virtual Environment Support

DevCtl automatically detects and activates Python virtual environments when running Python-related commands:

# Automatically activates .venv, venv, or other virtual environments
devctl run server -- python app.py
devctl run tests -- pytest
devctl run install -- pip install -r requirements.txt

# Works with any Python tool
devctl run format -- black .
devctl run lint -- flake8
devctl run notebook -- jupyter notebook

How it works

1. When running Python commands (python, pip, pytest, etc.), DevCtl checks for virtual environments
2. Looks for common venv directories: .venv, venv, env, .env, virtualenv
3. If using uv, it will detect the virtual environment via uv venv --status
4. Automatically sets VIRTUAL_ENV and updates PATH before running the command
5. The activation is logged in the service output

Supported Python Commands

DevCtl recognizes these as Python commands:

• Core: python, python3, python2, py, pip, pip3, pip2
• Package managers: pipenv, poetry, pdm
• Web frameworks: uvicorn, gunicorn, flask, django, django-admin
• Testing: pytest, py.test, unittest
• Linting/Formatting: mypy, pylint, flake8, black, isort, ruff
• Interactive: jupyter, ipython, notebook
• Others: streamlit, gradio, fastapi

Performance

All commands complete in ~1 second, including daemon startup if needed.

Python Virtual Environment Support

DevCtl automatically detects and activates Python virtual environments when running Python commands.

How it works

1. When running a Python-related command, DevCtl checks for virtual environments in:

   • .venv/
   • venv/
   • env/
   • .env/
   • virtualenv/
   • Or any directory detected by uv (if installed)

2. If found, it automatically activates the environment before running your command

3. Works with all Python tools:

   python, python3, pip, pip3, pytest, uvicorn, flask, django,
   gunicorn, celery, jupyter, ipython, mypy, black, flake8, pylint,
   isort, poetry, pipenv, conda, mamba, pdm, hatch, ruff, and more

Examples

# Automatically uses .venv/bin/python if .venv exists
devctl run api -- python app.py

# Works with any Python tool
devctl run server -- uvicorn main:app --reload
devctl run tests -- pytest -v

# Also works with npm scripts that use Python
devctl start dev  # If dev script runs Python, venv is activated

Notes

• No manual activation needed - it's completely automatic
• Supports both Unix-like systems and Windows
• Prefers uv for virtual environment detection when available
• Logs show when a venv is activated for debugging

Testing

Run the comprehensive test suite:

npm test

Tests cover all features including service lifecycle, logging, path resolution, and error handling.

Development

# Build TypeScript
npm run build

# Run tests
npm test

# Clean build
npm run clean

Troubleshooting

Service won't start: Check if script exists in package.json or command is valid.

Logs are empty: Some commands complete too quickly. Logs are buffered line-by-line.

Permission denied: Ensure you have execute permissions for the commands you're running.

Daemon issues: Use devctl killall to clean up and restart fresh.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

MIT © Productioneer