ANDO CLI Reference

Prerequisites

ANDO requires Docker to run builds in isolated containers. If Docker is not available, ANDO shows specific error messages:

Docker not installed - Shows installation instructions for your platform with a link to the Docker website.
Docker daemon not running - Shows platform-specific instructions to start Docker Desktop (Windows/macOS) or the Docker daemon (Linux).

Commands

Command	Description
`ando`	Run the build script in a Docker container.
`ando commit`	Commit all changes with AI-generated message.
`ando bump`	Bump version across all projects.
`ando docs`	Update documentation using Claude.
`ando release`	Interactive release workflow.
`ando ship`	Ship workflow (release without publish).
`ando verify`	Check build script for errors without executing.
`ando clean`	Remove artifacts, temp files, and containers.

Run Options

Flag	Description
`-f, --file <file>`	Use a specific build file instead of build.csando.
`-p, --profile <profiles>`	Activate build profiles (comma-separated).
`--read-env`	Load environment file without prompting.
`--verbosity <level>`	Set output verbosity (quiet\|minimal\|normal\|detailed).
`--no-color`	Disable colored output.
`--cold`	Always create a fresh container.
`--image <image>`	Use a custom Docker image.
`--dind`	Mount Docker socket for Docker-in-Docker builds.

Docker-in-Docker (DIND)

ANDO automatically detects when your build script uses operations that require Docker-in-Docker mode (such as Docker.Build, Docker.Push, Docker.Install, GitHub.PushImage, or Playwright.Test). This detection also scans child builds invoked via Ando.Build(). If DIND is needed but not enabled, ANDO prompts you:

(Y)es - Enable DIND for this run only
(A)lways - Enable DIND and save the setting to ando.config
Esc - Cancel the build

To skip the prompt, use the --dind flag, add dind: true to your ando.config file, or set the ANDO_DIND=1 environment variable.

Child build inheritance: When a parent build enables DIND, child builds invoked via Ando.Build() automatically inherit the DIND setting. The parent passes ANDO_DIND=1 to both the container environment and the host process environment, so child builds won’t prompt again for DIND mode. (The host process environment is needed because Ando.Build spawns child ando processes on the host.)

CI Server: When running on the ANDO CI Server, the Docker CLI is automatically installed in the build container for DIND builds. You do not need to call Docker.Install() in your build script — though it is harmless to include.

Configuration File

ANDO supports an optional ando.config file in the project root for persisting settings.

# ando.config
dind: true
readEnv: true
allowClaude: true

Setting	Description
`dind`	Enable Docker-in-Docker mode by default.
`readEnv`	Automatically load environment files without prompting.
`allowClaude`	Allow Claude CLI to run with elevated permissions without prompting.

Environment Files

ANDO looks for environment files in the project root: .env.ando (preferred) or .env (fallback).

Security check: If .env.ando exists but is not in .gitignore, ANDO warns that the file may contain secrets and prompts you:

(A)dd to .gitignore (default) - Automatically appends .env.ando to your .gitignore file
(C)ontinue anyway - Proceed without adding to .gitignore
Esc - Abort the build

Loading prompt: When environment variables are found, ANDO prompts:

(Y)es - Load for this run only
(n)o - Skip loading
for this (r)un - Load for this run and all sub-builds
(a)lways - Load and save readEnv: true to ando.config

Use --read-env or set readEnv: true in ando.config to skip the prompt and load automatically.

Claude Integration

Several ANDO commands use Claude CLI for AI-powered features:

Command	Claude Usage
`ando commit`	Generates commit messages from diffs
`ando bump`	Generates changelog entries and updates changelog files
`ando docs`	Reviews code changes and updates documentation

Requirements: Claude CLI must be installed (npm install -g @anthropic-ai/claude-code)

Permissions: Claude runs with --dangerously-skip-permissions to allow file edits without interactive prompts. On first use, ANDO prompts you to confirm:

(Y)es - Allow Claude for this run only
(n)o - Cancel the command
(A)lways - Allow Claude and save allowClaude: true to ando.config

To skip the prompt, add allowClaude: true to your ando.config file.

Commit Command

Commits all changes with an AI-generated message using Claude.

$ ando commit
Analyzing changes...

  src/Ando/Operations/GitHubOperations.cs
  website/src/content/providers/github.md

Generated commit message:
────────────────────────────────────────
docs: add options reference to GitHub provider
────────────────────────────────────────

Commit with this message? [Y/n] y

Bump Command

Bumps the version of all projects detected in build.csando.

ando bump [patch|minor|major]

What it does:

Detects projects from build.csando (Dotnet.Project, Npm directories)
Validates all versions match (prompts if mismatched)
Updates all project files (.csproj, package.json)
Generates changelog entry using Claude from commit history
Updates CHANGELOG.md and version badges
Commits the changes

Supported projects:

.csproj files via Dotnet.Project("path")
package.json in directories used with Npm.* operations

Docs Command

Uses Claude to review code changes and update documentation.

ando docs

What it does:

Syncs version badges in documentation files (index.astro, README.md) to the current project version
Gets commits since last git tag (or recent commits if no tag)
Analyzes each commit to understand what changed
Finds and updates relevant documentation files
Changes are left uncommitted for you to review

Files Searched and Updated

Claude searches for and updates these file types:

Pattern	Location	Description
`*.md`	Anywhere	Markdown documentation files
`*.astro`	`website/`	Astro page components
`*.js`	`website/`	JavaScript data files (operations, providers)
`llms.txt`	`public/`	LLM-friendly documentation (must stay in sync)

Files Skipped

File	Reason
`CHANGELOG.md`	Handled separately by `ando bump`
Internal refactoring	Only user-facing changes need docs

What Triggers Updates

Claude looks for commits that affect:

New features - Operations, commands, or capabilities
Changed behavior - Modified functionality that affects users
New options - Parameters, flags, or configuration settings
Examples - New use cases or updated patterns
CLI help - Command descriptions or usage

Example Output

$ ando docs
Analyzing 5 commit(s) since v0.9.58...
Claude is reviewing documentation...

Reading website/src/data/operations.js...
Updating Docker.Build options documentation...
Reading website/public/llms.txt...
Adding new --platform flag to llms.txt...

Documentation updated. Review changes and commit when ready.

Requirements: Claude CLI must be installed (npm install -g @anthropic-ai/claude-code)

Release Command

Interactive release workflow that orchestrates: commit, documentation, bump, push, and publish.

ando release           # Interactive checklist
ando release --all     # Skip checklist, run all steps
ando release --dry-run # Preview without executing
ando release --minor   # Specify bump type (default: patch)

Steps:

Build Verification - Runs ando run --read-env first
Commit - Commit uncommitted changes (uses ando commit) - skipped if no uncommitted changes
Docs - Update documentation (uses ando docs)
Bump - Bump version across all projects (uses ando bump) - skipped if no changes since last tag
Push - Push to remote repository - skipped if no remote tracking
Publish - Run ando run -p publish --dind --read-env

Steps are contextually enabled/disabled based on repository state.

Ship Command

Ship workflow — same as release but without the publish step. Use when you want to commit, bump, update docs, and push without building/publishing artifacts.

ando ship              # Interactive checklist
ando ship --all        # Skip checklist, run all steps
ando ship --dry-run    # Preview without executing
ando ship minor        # Specify bump type (default: patch)

Steps:

Build Verification - Runs ando run --read-env first
Commit - Commit uncommitted changes (uses ando commit) - skipped if no uncommitted changes
Bump - Bump version across all projects (uses ando bump) - skipped if no changes since last tag
Docs - Update documentation (uses ando docs)
Push - Push to remote repository - skipped if no remote tracking

Steps are contextually enabled/disabled based on repository state. Hooks use the command name ship (e.g., ando-pre-ship.csando).

Hooks

ANDO supports pre-build and post-build hooks that run before and after CLI commands. Hooks are .csando scripts that execute on the host machine.

Hook	When it runs
`ando-pre.csando`	Before ANY command
`ando-pre-{cmd}.csando`	Before specific command
`ando-post-{cmd}.csando`	After specific command
`ando-post.csando`	After ANY command

Quick example:

// scripts/ando-pre-bump.csando
var result = await Shell.RunAsync("dotnet", "test", "--no-build");
if (result.ExitCode != 0) throw new Exception("Tests failed");

👉 See full Hooks documentation for file locations, available APIs, environment variables, and more examples.

Cancellation (Ctrl+C)

ANDO handles Ctrl+C gracefully:

First Ctrl+C - Requests cancellation. The current step finishes, then the build stops.
Second Ctrl+C - Forces immediate exit (exit code 130).

Clean Options

Flag	Description
`--artifacts`	Remove the artifacts directory.
`--temp`	Remove temp directory.
`--container`	Remove the project’s warm container (clears package caches).
`--all`	Remove all of the above.

Project Files

ANDO uses and creates various files in your project directory:

Environment Files

File	Description
`.env.ando`	Preferred - Project-specific environment variables. Takes priority over `.env`.
`.env`	Fallback - Standard environment file, used if `.env.ando` doesn’t exist.

ANDO prompts before loading environment files (unless --read-env flag or readEnv: true in config).

Configuration Files

File	Description
`ando.config`	YAML configuration file for persistent settings (`dind`, `readEnv`).
`build.csando`	Build script (C# with Roslyn scripting).

Generated Files & Directories

Path	Description
`build.csando.log`	Plain-text log of the last build run. Overwrites on each run.
`.ando/cache/`	Package caches persist inside warm containers (not on host).
`.ando/tmp/`	Temporary files used during builds.
`artifacts/`	Default output directory for build artifacts.

Hook Scripts

File	Description
`ando-pre.csando`	Runs before any command.
`ando-pre-{cmd}.csando`	Runs before a specific command.
`ando-post-{cmd}.csando`	Runs after a specific command.
`ando-post.csando`	Runs after any command.

Hook scripts are searched in ./scripts/ first, then ./.

Logging

ANDO writes a plain-text log to build.csando.log in the project root. This file:

Is overwritten on each build run (not appended)
Contains the same output as the console (without ANSI color codes)
Includes timestamps, step names, and command output
Is useful for debugging failed builds or reviewing build history

Suggested .gitignore

Add these patterns to your .gitignore to exclude ANDO-generated files:

# ANDO build system
.env.ando
build.csando.log
.ando/
artifacts/

Explanation:

Pattern	Why ignore
`.env.ando`	Contains secrets (API keys, tokens, passwords). ANDO warns if not gitignored.
`build.csando.log`	Build output log, regenerated on each run.
`.ando/`	Cache directories (NuGet, npm) and temp files. Large and machine-specific.
`artifacts/`	Build outputs. Should be regenerated, not committed.

Optional:

# Optional: exclude config if it contains machine-specific settings
# ando.config

Most teams commit ando.config since it contains project-wide settings like dind: true.