codespacegen is a CLI that generates the following three files for Codespaces and Dev Container.
- Dockerfile
- devcontainer.json
- docker-compose.yaml
The latest release is downloaded automatically and installed into /usr/local/bin.
curl -fsSL https://raw.githubusercontent.com/taka1156/codespacegen/master/scripts/install.sh | bashTo change the install destination:
curl -fsSL https://raw.githubusercontent.com/taka1156/codespacegen/master/scripts/install.sh | INSTALL_DIR=$HOME/.local/bin bashAfter installation, csg is also available as a shortcut alias for codespacegen.
Main generated assets:
codespacegen_linux_amd64.tar.gzcodespacegen_linux_arm64.tar.gzcodespacegen_darwin_amd64.tar.gzcodespacegen_darwin_arm64.tar.gzcodespacegen_windows_amd64.exechecksums.txt
- Domain: rules and models
- internal/domain/entity
- internal/domain/service
- App: composition and orchestration
- internal/app
- Input adapters (CLI/JSON/defaults)
- internal/input
- Infra (interactive prompt I/O, file writing)
- internal/infra
- internal/infra/filewriter
- Workflows (use cases)
- internal/workflow/collect
- internal/workflow/assemble
- internal/workflow/generate
- internal/workflow/initialize
- Artifact generation
- internal/generator
- i18n resources
- internal/i18n
- Entry point: CLI
- cmd/codespacegen
Dependencies only point inward.
go run ./cmd/codespacegenBy default, files are generated under .devcontainer.
Run the version subcommand to display the current version of the binary.
codespacegen versionRun the init subcommand to generate a codespacegen.json template.
codespacegen initThe generated file serves as a starting point for customizing base images and VS Code extensions.
| Option | Default | Description |
|---|---|---|
-output |
. |
Output directory for codespacegen.json |
Run the update subcommand to self-update the binary to the latest release from GitHub.
codespacegen updateIf the binary is already up to date, a message is printed and the command exits successfully.
| Option | Default | Description |
|---|---|---|
-lang |
(auto-detect) | Language for CLI messages (en or ja). Defaults to system locale |
| Option | Default | Description |
|---|---|---|
-output |
.devcontainer |
Output directory |
-name |
(interactive, required) | Project name. Prompted every time and mapped to the name field in devcontainer.json |
-language |
(interactive, empty on Enter) | Programming language key. Prompted every time. Any profileName defined in the langs array of codespacegen.json (or the file specified by -image-config) can be used. If empty, no language-specific setting is used and alpine:latest is selected |
-service |
(interactive, app on Enter) |
Docker Compose service name. Prompted every time and reflected in both devcontainer.json and docker-compose.yaml |
-workspace-folder |
(interactive, /workspace on Enter) |
Workspace path inside the container. Prompted every time |
-timezone |
(interactive, default from common.timezone or UTC) |
Timezone inside the container. Prompted every time and reflected in ENV TZ and timezone setup in the Dockerfile |
-image-config |
codespacegen.json |
Local path or https:// URL for base image definitions. Supports top-level common defaults plus a langs array for per-language entries. image is required when runCommand or linuxPackages is specified |
-port |
(interactive, no ports on Enter) | Port mapping. For example, 3000 is normalized to 3000:3000, and 8080:3000 is also accepted. Prompted every time |
-compose-file |
docker-compose.yaml |
Compose file name |
-force |
false |
Overwrite existing files |
-lang |
(auto-detect) | Language for CLI messages (en or ja). Defaults to system locale |
-headless |
false |
Skip all interactive prompts. All required values must be supplied via flags |
Base image definitions are separated into codespacegen.json at the repository root.
- If the JSON file exists: values are loaded from the file
In addition, extension IDs from codespacegen.json (common.vscodeExtensions and per-language vscodeExtensions) are appended.
You can attach the JSON Schema in editors that support JSON Schema validation and completion.
{
"$schema": "./codespacegen.schema.json",
"langs": [
{
"profileName": "go",
"image": "golang:1.24-alpine"
}
]
}If codespacegen.json is at the repository root, ./codespacegen.schema.json points to the bundled schema file in this repository.
Language entries (langs array)
Each entry in langs requires profileName and supports the following fields (image is required when runCommand or linuxPackages is specified):
{
"langs": [
{
"profileName": "go",
"image": "golang:1.24-alpine",
"vscodeExtensions": ["golang.Go"]
},
{
"profileName": "moonbit",
"image": "ubuntu:24.04",
"runCommand": "curl -fsSL https://cli.moonbitlang.com/install/unix.sh | bash",
"vscodeExtensions": ["moonbit.moonbit-lang"]
},
{
"profileName": "gcc",
"image": "ubuntu:24.04",
"linuxPackages": ["gcc", "make", "git", "binutils", "libc6-dev"],
"vscodeExtensions": ["ms-vscode.cpptools"]
}
]
}The runCommand value is injected as a RUN step in the Dockerfile:
RUN curl -fsSL https://cli.moonbitlang.com/install/unix.sh | bashlinuxPackages specifies Linux system packages. They are merged with the default package list and installed by the package manager appropriate for the base image (e.g. apt for Debian/Ubuntu, apk for Alpine).
Shared defaults with common
{
"common": {
"timezone": "Asia/Tokyo",
"locale": {
"lang": "ja_JP.UTF-8",
"language": "ja_JP:ja",
"lcAll": "ja_JP.UTF-8"
},
"vscodeExtensions": [
"MS-CEINTL.vscode-language-pack-ja",
"streetsidesoftware.code-spell-checker"
]
},
"langs": [
{
"profileName": "go",
"image": "golang:1.24-alpine",
"vscodeExtensions": ["golang.Go"]
}
]
}Merge behavior:
commonis applied first as the base; per-language entries can only appendvscodeExtensionsvscodeExtensionsare merged in order and de-duplicatedtimezoneandlocalecan only be set incommon; they are not available in per-language entries- If timezone is not set in flags or
common,UTCis used
Example:
go run ./cmd/codespacegen \
-output .devcontainer \
-name "My Codespace" \
-language go \
-service app \
-workspace-folder /workspace \
-timezone Asia/Tokyo \
-compose-file docker-compose.yaml \
-forceExample using a remote JSON URL:
go run ./cmd/codespacegen -image-config https://example.com/my-base-images.json -language go -force- Only
https://URLs are supported.http://is rejected - If the JSON is missing or not specified, built-in Alpine defaults are used
Example exposing a port:
go run ./cmd/codespacegen -language go -port 3000 -forceIf -port is not specified, the CLI prompts for a port interactively during execution.
The generated docker-compose.yaml looks like this, with ports added only when a port is provided.
services:
app:
build: .
tty: true
volumes:
- ../:/workspacego test ./...