opcd

   __                  ___   
  / /__  _ __   ___ __| \ \  
 | / _ \| '_ \ / __/ _` || | 
< < (_) | |_) | (_| (_| | > >
 | \___/| .__/ \___\__,_|| | 
  \_\   |_|             /_/
    open · project · code

Reusable Dev Containers for any project — without modifying the repository.

Table of Contents

• Background
• Install
• Usage
• Configuration
• Template System
• File Injection
• API
• Contributing
• License

Background

opcd is a CLI that opens any project in VS Code Dev Containers using reusable, local templates.

Define your environment once and reuse it across projects.

Typical Dev Container workflows involve:

• Copying .devcontainer/ directories between projects
• Recreating environments repeatedly
• Committing configuration to repositories you do not control

opcd separates environment configuration from project code:

• Templates are stored locally
• Projects remain unchanged
• Containers are launched with a single command

Install

Dependencies

• VS Code with the Dev Containers extension
• Docker
• devcontainer CLI

pip install opcd

Usage

# Open a project (auto-detects template from container history, or uses default)
opcd open ~/projects/my-app

# Open with an explicit template
opcd open ~/projects/my-app opcd

Typical Workflow

opcd template new python-dev
opcd template edit python-dev
opcd open ~/projects/my-app python-dev

Project Switching

opcd list -a -i

Lists containers and allows reopening projects interactively.

Advanced Options

• Multiple template directories
• Verbose debugging (-v)
• Dry runs (--dry-run)
• Custom container paths

Internal Flow

1. Validate project path (must exist)
2. Resolve template (explicit → container history → settings default)
3. Launch VS Code Dev Container
4. Apply file injection rules

Configuration

opcd reads settings.json from:

~/.config/opcd/settings.json

Override the config directory:

OPCD_CONF_DIR=/custom/path opcd open ~/projects/my-app

The file is created automatically with defaults on first run.

settings.json

{
  "template_sources": ["~/.local/share/opcd/templates"],
  "default_template": "opcd",
  "template_write_dir": null
}

Template System

Default Location

~/.local/share/opcd/templates/

Configure additional paths via template_sources in settings.json (see Configuration).

File Injection

Inject files from the host into the container at startup.

Example

{
  "customizations": {
    "opcd": {
      "cp": [
        {
          "source": "${localEnv:HOME}/.config/myapp",
          "target": "/home/vscode/.config/myapp"
        }
      ]
    }
  }
}

Fields

Source Behavior

• Supports ${localEnv:VAR}
• Supports relative paths from .devcontainer/
• Missing environment variables cause the entry to be skipped

Copy Directory Contents

Use /. suffix:

{
  "source": "${localEnv:HOME}/.config/myapp/.",
  "target": "/home/vscode/.config/myapp/"
}

Copies directory contents instead of the directory itself.

Behavior Rules

• target/ copies into the directory
• Without trailing / copies as a file or directory
• override=false skips existing files
• Ownership and permissions are applied after copying

API

Full reference for all opcd commands and flags.

Global Flags

-v, --verbose   Enable debug output
--version       Show version and exit

opcd open

opcd open <path> [template] [options]

Open a project in VS Code using a devcontainer template.

Arguments

• <path> — Project directory (must exist)
• [template] (optional) — Template name, path to a devcontainer.json, or path to a directory containing it. Paths must start with ./, ../, /, or ~/. If omitted, opcd resolves in this order:
  1. Most recently running container for this project path
  2. Most recently stopped container for this project path
  3. default_template from settings.json (error if not set)

Options

opcd list

opcd list [-a] [-i]

List dev containers.

Interactive mode prompts Open [1-N]: — selecting a number reopens the project in VS Code.

opcd prune

opcd prune [path] [options]

Remove stopped dev containers. Either [path] or --all-projects is required.

Arguments

• [path] (optional) — Limit pruning to containers for this project directory.

Options

opcd template

opcd template <subcommand>

Manage dev container templates.

opcd template new

opcd template new <name> [base] [options]

Create a new template by copying a base template.

opcd template edit

opcd template edit <template>

Open a template directory in VS Code for editing.

opcd template list

opcd template list [--long]

List available templates.

opcd template default

opcd template default [name]

Get or set the default template.

• Without name: prints the current default.
• With name: sets default_template in settings.json.

opcd template source

opcd template source <subcommand>

Manage template search paths stored in settings.json.

opcd template source list

opcd template source list

Print all configured template search paths, one per line.

opcd template source add

opcd template source add <path>

Append <path> to template_sources in settings.json. Prints a notice and exits cleanly if already present.

opcd template source remove

opcd template source remove <path>

Remove <path> from template_sources in settings.json. Exits with an error if not found.

opcd completion

opcd completion bash
opcd completion zsh
opcd completion fish

Print the shell completion setup command for the given shell.

Add to your shell rc file for persistent completion:

# bash (~/.bashrc)
eval "$(opcd completion bash)"

# zsh (~/.zshrc)
eval "$(opcd completion zsh)"

# fish (~/.config/fish/config.fish)
eval (opcd completion fish)

Contributing

Ask questions, report bugs, or request features in Issues.

PRs welcome. Open an issue first for significant changes.

Run tox (or pytest for a single-interpreter run) before submitting.

License

MIT © Nasser Alansari (dacrystal)

See LICENSE.