devlaunch

A streamlined CLI for devpod with intuitive autocomplete and fzf fuzzy selection.

Continuous Integration Status

Installation

Pixi (Recommended)

pixi global install --channel conda-forge --channel https://prefix.dev/blooop devlaunch

This installs devlaunch along with devpod and all dependencies automatically.

Pip

pip install devlaunch

Note: When using pip, you must install devpod separately. If devpod is not on PATH, every command that needs it prints a single install hint on stderr and exits 127 (the shell's "command not found" code). dl --help and dl --version keep working without it.

Shell Completions

After installation, set up shell completions:

dl --install
source ~/.bashrc  # or restart your terminal

Usage

dl                               # Interactive workspace selector (fzf)
dl <user/repo>                   # Start workspace and attach shell
dl <user/repo> <cmd>             # Run workspace command (stop, code, etc.)
dl <user/repo> -- <command>      # Run shell command in workspace

Workspace Sources

dl myproject                     # Existing workspace by name
dl user/repo                     # Create from GitHub repo
dl user/repo@branch              # Create from specific branch
dl ./path                        # Create from local path

Workspace Commands

Command	Description
`dl <user/repo> stop`	Stop the workspace
`dl <user/repo> rm, prune`	Delete the workspace
`dl <user/repo> code`	Open in VS Code
`dl <user/repo> restart`	Stop and start (no rebuild)
`dl <user/repo> recreate`	Recreate container
`dl <user/repo> reset`	Clean slate (remove all, recreate)
`dl <user/repo> -- <command>`	Run shell command in workspace

Options

Option	Description
`--devcontainer <variant\|path>`	Use a non-default `devcontainer.json`. A bare name means `.devcontainer/<name>/devcontainer.json`. Stored with the workspace, so pass it once.

Projects with demanding devcontainers — several variants, compose sidecars, or a host-side initializeCommand that has to tell branch workspaces apart — are covered in docs/devcontainer-projects.md.

GitHub Authentication

Every workspace dl opens inherits the host's GitHub login, so gh is already authenticated inside the container and the devcontainer.json does not have to arrange anything for it. devpod forwards the ssh agent and git credentials on its own, but nothing else carries gh.

devlaunch takes the token from GH_TOKEN, GITHUB_TOKEN, or gh auth token, whichever answers first, and hands it to the container as GH_TOKEN. That reaches any image and any container user, unlike a bind-mount of ~/.config/gh, and it works whether the host keeps its token in hosts.yml or in a keyring. The token is passed to devpod through a private file and through devpod's own environment, never on a command line, so it does not appear in ps. The container still needs gh installed for the login to be of any use. Check a workspace with:

dl <workspace> -- gh auth status

Who gets the token

Everything running in the container does — including a postCreateCommand from a repo you did not write. dl someone/repo builds and runs that project's devcontainer with your GitHub token in its environment, and a gh auth login token usually carries repo, workflow, gist and read:org scopes. devpod already forwards the ssh agent to every workspace, so this is not a new trust boundary, but it is a wider one. Skip it for a repo you have not read:

DEVLAUNCH_NO_GH_TOKEN=1 dl someone/repo

Variable	Description
`DEVLAUNCH_NO_GH_TOKEN=1`	Do not forward the host's GitHub login into workspaces

When the token changes

dl refreshes the token on every start, so rotating it on the host is enough for any workspace that gets started or restarted afterwards. Attaching to a workspace that is already running skips that step, and the token it was given at startup stays in place — including one it was given before you set DEVLAUNCH_NO_GH_TOKEN. Run dl <workspace> restart to replace it.

Global Commands

Command	Description
`dl --ls`	List all workspaces
`dl --install`	Install shell completions
`dl --purge [-y]`	Remove all devlaunch data
`dl --prune-worktrees [days]`	Remove unused worktrees (default: 30 days)
`dl --refresh`	Refresh completion cache
`dl --help, -h`	Show this help
`dl --version`	Show version

Examples

dl                               # Select workspace with fzf
dl devpod                        # Open existing workspace
dl loft-sh/devpod                # Create from GitHub
dl blooop/devlaunch@main         # Create from specific branch
dl ./my-project                  # Create from local folder
dl blooop/devlaunch code         # Open in VS Code
dl blooop/devlaunch -- make test # Run command in workspace
dl blooop/devlaunch stop         # Stop workspace

Features

Fuzzy Selection: When called without arguments, uses fzf for interactive workspace selection
Smart Completion: Tab completion for workspaces, GitHub repos (owner/repo format), and paths
GitHub Shorthand: Use owner/repo instead of full URLs - automatically expands to github.com/owner/repo
Branch Support: Specify branches with owner/repo@branch syntax
Fast Autocomplete: Completion cache for ~3ms response time (vs ~700ms without cache)

Worktree Backend

For git repositories, devlaunch uses an efficient worktree backend by default:

Efficient Storage: Repos are cloned once to ~/.cache/devlaunch/repos/owner/repo/, then git worktrees are created for each branch
Shared Git Objects: All branches share git objects, saving disk space
Lazy Fetch: Remote updates are only fetched if the configured interval has elapsed (default: 1 hour)

Container Sharing Mode

Use --shared to share a single container across multiple branches of the same repo:

dl --shared owner/repo@branch1  # Creates container "owner-repo"
dl --shared owner/repo@branch2  # Reuses "owner-repo" container

Pre-warming

Use --warm to prepare a workspace without attaching a shell:

dl --warm owner/repo@branch  # Creates container in background

Shell Completion

After running dl --install, you get intelligent tab completion:

Workspace names from your devpod list
Known GitHub owners and repositories from your workspaces
File/directory paths when starting with ./, /, or ~
All global flags (--ls, --install, etc.) and workspace commands

Development

This project uses pixi for environment management.

# Run tests
pixi run test

# Run full CI suite
pixi run ci

# Format and lint
pixi run style

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

devlaunch-0.0.8.tar.gz (38.1 kB view details)

Uploaded Aug 7, 2026 Source

Built Distribution

If you're not sure about the file name format, learn more about wheel file names.

The dropdown lists show the available interpreters, ABIs, and platforms. Enable javascript to be able to filter the list of wheel files.

devlaunch-0.0.8-py2.py3-none-any.whl (42.2 kB view details)

Uploaded Aug 7, 2026 Python 2Python 3

File details

Details for the file devlaunch-0.0.8.tar.gz.

File metadata

Download URL: devlaunch-0.0.8.tar.gz
Upload date: Aug 7, 2026
Size: 38.1 kB
Tags: Source
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.12.13

File hashes

Hashes for devlaunch-0.0.8.tar.gz
Algorithm	Hash digest
SHA256	`10340746bc1d8e596b3178907bffd267d0110bb5d1cb1549287520550de25ac9`
MD5	`a7cbd0e8dca2a5461b4e792a73018bc3`
BLAKE2b-256	`e521fff91beb803b1184dbcc89fd3256dc13ce4a3b5f26e45a3e1e310596126f`

See more details on using hashes here.

File details

Details for the file devlaunch-0.0.8-py2.py3-none-any.whl.

File metadata

Download URL: devlaunch-0.0.8-py2.py3-none-any.whl
Upload date: Aug 7, 2026
Size: 42.2 kB
Tags: Python 2, Python 3
Uploaded using Trusted Publishing? No
Uploaded via: twine/7.0.0 CPython/3.12.13

File hashes

Hashes for devlaunch-0.0.8-py2.py3-none-any.whl
Algorithm	Hash digest
SHA256	`018e913eb13aeddfd3018e0668c04e7ea0164f5810853da3c0b1dba76cfa08c2`
MD5	`f8c898d935517515c6584b7dc4495e5a`
BLAKE2b-256	`1a76792b1a1467605cb0f1f86c8f3b72eab21603bf377851d9d922e8b821369b`