Commands
CLI Commands
The Dex CLI (dex) provides commands for scaffolding projects, syncing upstream updates, managing release tags, building, and running applications.
Overview
dex scaffold <dir> [options]
dex sync [--interactive] [options]
dex tag <patch|minor|major>
dex build
dex start [-p]
dex -v / --version [-f]dex scaffold
Scaffold a new Dex project in the specified directory.
dex scaffold <dir> [options]When run, dex scaffold prompts you to choose the project type (spa or mpa), downloads and extracts the template archive and framework package archives (router, server, dev, pie) into the packages/ directory, initializes .dex/metadata.json, and runs bun install by default.
Options
| Option | Description |
|---|---|
--repo <owner/repo> | GitHub repository containing release templates (default: patrickaigbogun/dex) |
--tag <tag|latest> | Release tag to download template from (default: latest) |
--packages-repo <owner/repo> | GitHub repository containing dex-package-*.tgz assets |
--packages-tag <tag|latest> | Release tag for dex-package-*.tgz assets (default: template tag) |
--template <path> | Use a local template .tgz archive instead of downloading from GitHub |
--template-url <url> | Download template .tgz archive from a direct URL (skips GitHub API) |
--no-install | Do not run bun install after scaffolding |
Examples
# Scaffold in a new directory
dex scaffold my-app
# Scaffold using a specific release tag
dex scaffold my-app --tag v0.1.44
# Scaffold from a custom GitHub repository
dex scaffold my-app --repo myorg/dex-templates --tag v1.0.0
# Scaffold from a local archive without installing dependencies
dex scaffold my-app --template ./custom-template.tgz --no-install
# Scaffold from a direct URL
dex scaffold my-app --template-url https://example.com/templates/dex-template-spa.tgzdex sync
Sync upstream template changes and updates into an existing Dex project.
dex sync [options]dex sync reads template metadata from .dex/metadata.json, fetches the diff manifest (dex-diff-<tag>.json) from the release, downloads the template archive, and copies changed files into your project root while preserving project metadata.
Options
| Option | Description |
|---|---|
--interactive | Interactively select which files to sync from the release diff |
--repo <owner/repo> | Template GitHub repository (default: read from .dex/metadata.json or DEX_TEMPLATE_REPO) |
--tag <tag> | Release tag to sync with (default: releaseTag from metadata or latest release) |
Examples
# Automatically sync all changed files from the current/latest release
dex sync
# Interactively choose which changed files to apply
dex sync --interactive
# Sync against a specific release tag and repository
dex sync --repo myorg/dex --tag v0.2.0dex tag
Bump SemVer version tags and push the tag to the git remote.
dex tag <patch|minor|major>Inspects existing git tags matching v*, determines the current highest SemVer version, computes the incremented version, creates the git tag, and pushes it to origin.
Arguments
| Argument | Description | Example |
|---|---|---|
patch | Bump SemVer patch version | v0.1.44 → v0.1.45 |
minor | Bump SemVer minor version | v0.1.44 → v0.2.0 |
major | Bump SemVer major version | v0.1.44 → v1.0.0 |
Examples
# Create and push a patch release tag
dex tag patch
# Create and push a minor release tag
dex tag minor
# Create and push a major release tag
dex tag majordex build
Build the Dex application for production.
dex buildDiscovers the project root (by looking for dex.config.*, config/dex.config.*, or package.json with a dex property) and runs bun run build.
dex start
Start the Dex application in development or production mode.
dex start [-p]Discovers the project root, reads configuration from dex.config.* (or package.json), resolves the configured port, and starts the server.
Options
| Option | Description |
|---|---|
-p | Production mode. Sets NODE_ENV=production and runs bun run start. Without -p, runs in development mode (bun run dev). |
Examples
# Start development server
dex start
# Start production server
dex start -pVersion Flags
Check the version of the Dex CLI and scaffolded project template.
# Show CLI version
dex -v
dex --version
# Show CLI version and framework template version
dex --version -f
dex -v -fOptions
| Flag | Description |
|---|---|
-v, --version | Display the @dex/cli version (e.g. dex 0.1.0) |
-f | Used with --version to also display the template version from .dex/metadata.json (e.g. template: v0.1.44) |
Environment Variables
The Dex CLI supports the following environment variables:
| Variable | Description | Default |
|---|---|---|
DEX_TEMPLATE_REPO | Default GitHub template repository (owner/repo) | patrickaigbogun/dex |
DEX_TEMPLATE_TGZ | Path to local template .tgz archive (skips GitHub API) | — |
DEX_TEMPLATE_URL | Direct URL to template .tgz archive (skips GitHub API) | — |
DEX_PACKAGE_REPO | GitHub repository (owner/repo) for dex-package-*.tgz assets | Template repo |
DEX_PACKAGE_TAG | Release tag for dex-package-*.tgz assets | Template tag |
DEX_CACHE_DIR | Directory for caching downloaded templates and packages | OS cache directory |
DEX_TEMPLATE_CACHE_TTL_MS | Cache TTL in milliseconds for latest release downloads | 1800000 (30m) |
DEX_FETCH_TIMEOUT_MS | Network timeout in milliseconds for GitHub API requests | 30000 (30s) |
GITHUB_TOKEN | GitHub Personal Access Token to avoid rate limits or access private repositories | — |
See Also
- Scaffold — Guide to scaffolding a new project
- CLI Flags — Quick reference for CLI flags
- Your First App — Step-by-step tutorial