The Doh CLI system consists of two main components:

1. Runtime CLI - Base commands for managing Doh installations and projects
2. Project CLI - Commands for managing Doh projects, packages, and deployments

This guide covers:

• Runtime CLI installation and basic commands
• Project CLI for application management
• Package and configuration management
• Dohball creation and management
• Backup and restore capabilities
• Cache management and documentation
• Process management and export tools
• Extending the CLI with custom commands

Runtime CLI

The Runtime CLI provides commands for managing Doh installations, initializing projects, and serving as a wrapper for Bun commands.

Initial Installation

To install Doh for the first time:

Windows:

powershell -c "irm deploydoh.com/install.ps1 | iex"

Mac/Linux/Unix:

curl -fsSL https://deploydoh.com/install | bash

After installation, you can use the doh command to manage both Doh and Bun runtimes.

Main Menu

Run doh without any arguments to access the interactive main menu:

doh

This presents options to:

• Run Project - Execute the current Doh project
• Initialize - Start or repair Doh projects and modules
• Install Runtimes - Install/uninstall Doh or Bun
• Exit - Quit the application

Initialization Menu

Access the initialization menu with:

doh init

Options include:

• Doh Project - Standard Doh project initialization (rerun safe)
• Doh Module - Quick module creation
• Doh Module (Wizard) - Guided module setup
• Doh w/ Webserver - Doh project with Express webserver (safe for existing projects)
• Webserver from URL - Initialize webserver and clone from a URL
• Back to Main Menu

Direct command options:

doh init project     # Initialize a standard Doh project
doh init doh         # Same as 'project' (alternative command)
doh init module      # Initialize a quick module 
doh init wizard      # Initialize a module with the wizard interface
doh init webserver              # Initialize a Doh webserver project
doh init webserver clone [url]  # Initialize and clone from a URL (prompts if URL omitted)

Runtime Management Commands

Install/Upgrade Doh

These commands can be used for both initial installation and subsequent upgrades:

doh install doh     # Install or upgrade Doh globally

Install/Upgrade Bun

doh install bun     # Install or upgrade Bun globally

Install/Uninstall Node.js (via Volta)

Manage Node.js installation using Volta.

doh install node     # Install Node.js globally via Volta (installs Volta if needed)
doh uninstall node   # Uninstall Node.js managed by Volta

Bun Passthrough

Execute Bun commands through Doh (Used with bun symlink to avoid installing bun globally):

doh bun [commands]  # Run Bun commands (e.g., doh bun pm trust --all)

Project CLI

The Project CLI provides commands for managing Doh projects, packages, configurations, deployments, and backups. It integrates with Doh's core systems, including the auto-packager, Dohballs, package management, and pod configurations.

All commands of the Doh Project CLI core are compatible with the --confirm-all flag that shortcuts prompts

Application Management

run

Start the Doh application.

doh run              # Run with auto-packager
doh run no-pack      # Run without auto-packager or installer
doh run pod.yaml     # Run with specific pod configuration (inherits from /pod.yaml)
doh run <module name> # Run with only the specified module (and its dependencies) loaded
doh run help         # Show detailed help for the run command

update

Run the Auto-Packager to scan, analyze, and generate manifests for your Doh project. This command handles packaging, build processes, and reports on available updates from remote hosts. It reads your code, checks for dependency updates, and updates manifests. This command is also run automatically at application boot but often gets lost in console spam, so it's useful to run manually to stay updated and see what's available.

doh update

Package Management

These commands also clean up obsolete files from previous versions based on the dohball.json.

Auto-Installer: NPM Dependencies

Doh includes an Auto-Installer that automatically manages npm dependencies based on your load statements. Instead of manually using Doh.Install(), you can simply import npm packages in your load blocks and the Auto-Installer will handle the installation.

How the Auto-Installer Works:

• Automatic Detection: Scans declarative load blocks in Doh.Module() and Doh.Package() declarations for import statements referencing npm packages
• Smart Installation: Installs packages at appropriate versions based on import specifiers in declarative load blocks
• Version Pinning: Supports full semver version pinning in declarative load blocks only (e.g., 'import React from "react@^18.0.0"')
• Complete Workflow: The Auto-Installer is part of the doh upgrade command which runs doh update before and after installations to ensure manifests are current

Example Usage (Declarative Load Blocks Only):

// ✅ WORKS: Declarative load block in Doh.Module() - Auto-Installer will run
Doh.Module('my_module', [
  'import React from "react@^18.0.0"',        // Auto-installs React 18.x.x
  'import axios from "axios"',                 // Auto-installs latest axios
  'import { format } from "date-fns@2.30.0"', // Auto-installs specific version
], function(React, axios, format) {
  // Your code here - dependencies are automatically installed
});

// ❌ WORKS ONLY IN BROWSER: Dynamic Doh.load() - No auto-installation
// Due to Doh's automatic esm.sh failover loader, even uninstalled
// npm dependencies can be used with version pinning in the browser.
Doh.Module('other_module', [], async function() {
  // This will fail if packages aren't already installed
  const [React, axios] = await Doh.load([
    'import React from "react@^18.0.0"',  // Semver accepted but ignored for installation
    'import axios from "axios"'
  ]);
});

Migration from Doh.Install():

// OLD WAY (still works but deprecated)
Doh.Install('my_module', {
  'npm:react': '^18.0.0',
  'npm:axios': '',
});

// NEW WAY (recommended)
Doh.Module('my_module', [
  'import React from "react@^18.0.0"',
  'import axios from "axios"',
], function(React, axios) {
  // Dependencies auto-installed by doh upgrade
});

install

Install specified Doh packages from remote Dohball hosts configured via dohball_host in pod.yaml. This command is ONLY for consuming remotely hosted Dohballs - it downloads and installs packages directly from HTTP/HTTPS hosts. Local code in your project is automatically made available by the Auto-Packager without any installation step. Runs the packager after installation, which includes cleanup of obsolete files from previous versions based on dohball.json.

doh install package1 [package2...]  # Install specific packages from remote hosts
doh install                       # Install all available packages from remote hosts

upgrade

Complete dependency management workflow that handles both package upgrades and npm installations. This command performs the following sequence:

1. Initial Update: Runs doh update to scan code, check remote hosts for updates, and refresh manifests
2. Dohball Upgrades: Compares local versions with remote host versions and installs newer versions from configured dohball_host sources
3. NPM Auto-Installation: Automatically installs any npm packages that are imported in load blocks but not yet installed (via the Auto-Installer)
4. Manifest Refresh: If any installations were performed, runs doh update again to refresh manifests with the new dependencies

This command provides complete dependency management - you typically don't need to run doh update separately when using doh upgrade.

doh upgrade                     # Upgrade all remotely installed packages and install npm deps
doh upgrade package1 [package2] # Upgrade specific remotely installed packages

reinstall

Reinstall all or specific remotely installed Doh packages from their original hosts. Runs the packager after reinstallation, which includes cleanup of obsolete files from previous versions based on dohball.json. This is primarily for fixing corrupted installations or refreshing from the latest remote versions.

doh reinstall                     # Reinstall all remotely installed packages
doh reinstall package1 [package2] # Reinstall specific remotely installed packages

Configuration Management

pod

Show or set pod.yaml settings using dot notation. Arrays are auto-detected via MOC metadata or existing values.

doh pod express_config.port                    # Show current value and inheritance
doh pod express_config.port 3000              # Set a value
doh pod ~~express_config.port                 # Add compile-time removal directive
doh pod inherits /path/to/pod.yaml            # Add to inherits array
doh pod inherits ~/path/to/pod.yaml           # Remove from inherits array immediately
doh pod dohball_host https://host.com         # Add to dohball_host array
doh pod dohball_host ~https://host.com        # Remove from dohball_host array immediately

bootpod

Show or set boot.pod.yaml settings using dot notation. Arrays are auto-detected via MOC metadata or existing values.

doh bootpod host_load package1                # Add to host_load array
doh bootpod host_load ~package1               # Remove from host_load array immediately
doh bootpod express_config.port 3000          # Set a value in boot.pod.yaml
doh bootpod ~~host_load                       # Add compile-time removal directive

inherits (Backward Compatibility)

Manage pod inheritance. Recommended: Use doh pod inherits instead.

doh inherits /path/to/pod.yaml                # Add inheritance
doh inherits ~/path/to/pod.yaml               # Remove inheritance immediately

host_load (Backward Compatibility)

Manage Doh package autoloading in Bun/Node.js. Recommended: Use doh bootpod host_load instead.

doh host_load package1 [package2]            # Add packages
doh host_load ~package1 [package2]           # Remove packages immediately

dohball_host (Backward Compatibility)

Manage Dohball hosts. Recommended: Use doh pod dohball_host instead.

doh dohball_host https://host.com             # Add host
doh dohball_host ~https://host.com            # Remove host immediately

Syntax Guide:

• ~value = Remove value immediately from file
• ~~setting = Add compile-time removal directive (e.g., ~~debug_mode: true)
• Arrays are auto-detected and managed intelligently
• Empty arrays are automatically cleaned up (removed from file)

Dohball Management

bake

Create Dohballs for exposed packages. This process identifies files removed since the last version and records them in dohball.json for cleanup during installation.

doh bake                     # Bake all exposed packages
doh bake package1 [package2] # Bake specific packages

rebake

Force recreation of Dohballs. This process identifies files removed since the last version (if one exists) and records them in dohball.json for cleanup during installation.

doh rebake                     # Rebake all packages
doh rebake package1 [package2] # Rebake specific packages

compile-dohball-manifest

Create the Dohball hosting manifest from locally hosted Dohballs.

doh compile-dohball-manifest

do-removals

Manually process the removals list found in the dohball.json of installed packages, deleting obsolete files. May prompt for confirmation before deleting files unless --confirm-all is used.

doh do-removals

status

Show Dohball status, including installed versions, remote versions, and update availability.

doh status         # Show basic status
doh status verbose # Show detailed status with integrity info, paths, and symlink details

enshrine

Create a tagged backup. If no tag is provided, it runs doh codify to create a standard auto-versioned backup.

doh enshrine <tag>

enact

Restore from a backup. If no version or tag is specified, it displays a menu of available codex and shrine backups.

doh enact                # Show available backups
doh enact <version|tag>  # Restore a specific backup

Cache Management

Most clear-* commands prompt for confirmation. Use the force argument or the --confirm-all flag to bypass these prompts (e.g., doh clear-pod force or doh clear-pod --confirm-all).

clear-pod

Clear pod cache and manifest.

doh clear-pod

clear-packager

Clear auto-packager output and manifests (includes package.cache.json, core_package.cache.json, and compiled_dohball_manifest.json).

doh clear-packager

clear-build

Clear the build directory at /dist containing compiled bundles. (Not part of clear-all)

doh clear-build

clear-doh-cache

Clear Doh cache files.

doh clear-doh-cache

clear-all

Clear pod cache/manifest and auto-packager manifests/caches (equivalent to doh clear-pod force and doh clear-packager force). Does not clear the build directory (/dist) or hosted Dohballs.

doh clear-all

Documentation

compile-docs

Generate documentation by consolidating project .md files.

doh compile-docs                     # Generate markdown docs (/doh_js/manifests/doh.md)
doh compile-docs yaml                # Generate YAML docs (/doh_js/manifests/doh.yaml)
doh compile-docs json                # Generate JSON docs (/doh_js/manifests/doh.json)
doh compile-docs txt                 # Generate plain text docs (/doh_js/manifests/doh.txt)
doh compile-docs json-txt            # Generate JSON-as-text docs (/doh_js/manifests/doh.txt)
doh compile-docs [format] --skip-toc # Generate docs without the Table of Contents

Process Management

pm2

Configure PM2 process management.

Uses Doh.pod.pm2

doh pm2 setup       # Set up PM2 configuration
doh pm2 stop        # Stop the process
doh pm2 restart     # Start/Restart the process
doh pm2 delete      # Delete the process
doh pm2 log         # View/tail logs

Export

export

Export a Doh module to a static HTML file.

doh export            # Export using default pod.yaml
doh export pod.yaml   # Export using a specific pod configuration

The export command creates a completely self-contained HTML file that bundles your Doh application with all its dependencies. See Export Tool Documentation for comprehensive details.

Extending the CLI

Custom Command Registration

Register new commands using Doh.CLI():

Doh.CLI('packageName', {
  'commandName': {
    file: 'path/to/implementation.js',
    help: 'Command description and usage'
  }
});

Command Implementation

Command implementation files should be ES modules:

// implementation.js
const args = process.argv.slice(3); // Get command arguments
// Command logic
export default null; // Export is ignored

CLI Manifest

Commands are compiled into /.doh/manifests/cli_manifest.json:

{
  "packageName": {
    "commandName": {
      "file": "/path/to/implementation.js",
      "help": "Command description and usage"
    }
  }
}

Best Practices

1. Command Names

   • Use descriptive, action-based names.
   • Follow kebab-case convention.
   • Group related commands with common prefixes.

2. Help Text

   • Include command purpose and usage examples.
   • Document all arguments and options.

3. Implementation

   • Handle errors gracefully.
   • Provide clear feedback.
   • Confirm destructive operations.

4. Documentation

   • Keep command documentation updated.
   • Include common use cases.
   • Document side effects.