CLI

The Putnami CLI is the single entry point for your workspace. It abstracts the underlying toolchains and provides a consistent interface for developers, CI systems, and AI agents.

Installation

curl -fsSL https://putnami.dev/install.sh | bash

The CLI is a single static Go binary with zero runtime dependencies. In a workspace with Go sources, you can also use the wrapper script ./putnamiw which auto-builds the CLI from source.

Job commands

Job commands are provided by extensions and run across projects:

putnami build .              # Build the current project
putnami test --impacted      # Test only what changed
putnami lint --all           # Lint the whole workspace
putnami serve my-app         # Serve an app with its dependencies
putnami publish .            # Publish a package
putnami format .             # Format code

Run multiple jobs in a single invocation:

putnami lint,test,build --impacted

Jobs run sequentially in the order specified, all sharing the same project selection.

Command aliases

Single-letter shortcuts for common jobs:

Alias	Command
b	build
t	test
l	lint
s	serve
f	format
p	publish

Define custom aliases in putnami.workspace.json:

{
  "aliases": {
    "ci": "lint,test,build",
    "dev": "serve"
  }
}

Structured commands

These built-in commands manage workspace infrastructure:

putnami workspace

• putnami workspace init — Initialize a new workspace in the current directory
  • --project <name> — Scaffold an initial project
  • --project-path <path> — Custom path for the initial project
• putnami workspace describe — Show workspace configuration
• putnami init — Alias for workspace init

putnami projects

• putnami projects list — List all projects with paths and tags
• putnami projects create <name> --template <template> — Scaffold a new project from a template
• putnami projects describe <project> — Show project details
• putnami projects sync — Sync project configuration (e.g., Go workspace)
• putnami projects tag <project> [tags] — Manage project tags

putnami extensions

• putnami extensions install — Install extensions from workspace config
• putnami extensions update — Update extensions to latest compatible versions
• putnami extensions list — List active extensions and their status
• putnami extensions remove <ext> — Remove an installed extension
• putnami extensions validate [path] — Validate an extension manifest
• putnami extensions test [path] — Run extension tests
• putnami extensions package [path] — Package an extension for distribution

putnami templates

• putnami templates install — Install templates from putnami.workspace.json
• putnami templates update — Update to latest compatible versions
• putnami templates list — List configured and discovered templates
• putnami templates remove <name> — Remove an installed template
• putnami templates validate [path] — Validate a template manifest
• putnami templates test [path] — Test a template by rendering it
• putnami templates package [path] — Package a template for distribution

putnami upgrade

• putnami upgrade — Upgrade everything: CLI, extensions, templates, and framework dependencies
• putnami upgrade --cli — Only upgrade the CLI binary
• putnami upgrade --extensions — Only upgrade extensions and templates
• putnami upgrade --deps — Only upgrade framework dependencies

Flags can be combined. When no flags are given, all phases run. See the Upgrade Putnami guide for details.

putnami deps

• putnami install — Install workspace dependencies across all active technologies. Also accepts an extension name (e.g., putnami install @putnami/go) to download and install that extension.
• putnami deps install — Install dependencies and run extension workspace installers

putnami scopes

• putnami scopes list — List all scopes with project counts, tags, and groups

putnami config

• putnami config show — Show merged configuration
• putnami config set <key> <value> — Set a value (dot-notation paths supported)

putnami cache

• putnami cache clean — Delete cached job results

putnami sessions

• putnami sessions list — List recorded job sessions
• putnami sessions inspect <id> — Show details for a session

putnami version

• putnami version list — List installed CLI versions
• putnami version use <name> — Switch active CLI version
• putnami version update — Download latest CLI version

Project targeting

Target expressions

putnami build /typescript/frameworks/web     # Exact project by ID
putnami build /typescript/...                # All projects under /typescript/
putnami build ./relative-path                # Relative to current directory
putnami build web                            # Alias (from projectAliases)
putnami build frontend                       # Group (from groups)
putnami build /a,/b,-/c                      # Union and subtraction

Flags

Flag	Purpose
.	Current project (or all projects under current directory)
--impacted	Projects affected by git changes (propagates through dependency graph)
--all	Every project in the workspace
--projects <list>	Comma-separated project names
--tag <tags>	Filter by tags (comma-separated). Overrides workspace excludeTags for matched tags.
--exclude-tag <tags>	Exclude by tags (comma-separated)
--exclude <names>	Exclude by name (comma-separated)
--baseline <branch>	Custom git baseline for --impacted

Default behavior

When no target is given:

• Inside a project directory — targets that project
• Inside a parent directory (e.g., typescript/) — targets all projects under it
• At the workspace root — targets all projects

Execution flags

Flag	Purpose
--no-cache	Force re-execution (skip cache reads, still writes)
--watch, -w	Re-run on file changes (150ms debounce)
--plan	Show execution plan without running
--verbose, -v	Show job results and diagnostics
--debug	Stream all job events in real-time (implies --verbose)
--dry-run	Show changes without applying
--continue-on-error	Don't abort on first failure
--max-parallel <n>	Cap concurrent jobs (default: CPU cores, 0 = unlimited)
--retry <n>	Retry transient failures
--skip-ci	Skip execution when CI=true

Output modes

Flag	Format	Use case
(default)	Text with progress bars	Interactive terminal
--output=jsonl	Streaming JSONL events	CI integration, programmatic consumption
--output=cloud-logging	Google Cloud structured JSON	Cloud Run (auto-detected via K_SERVICE)

Environment variables: PUTNAMI_OUTPUT=jsonl, PUTNAMI_VERBOSE=true, PUTNAMI_QUIET=true, PUTNAMI_NO_COLOR=true.

Global flags

Flag	Purpose
--help, -h	Show help
--version	Show CLI version
--quiet, -q	Suppress non-error output
--no-color	Disable color output
--color	Force color output
--profile <path>	Collect trace events (Chrome trace format)

Shell completion

The install script sets up completions automatically. Manual setup:

# Bash
putnami completion bash > ~/.local/share/bash-completion/completions/putnami

# Zsh (oh-my-zsh)
mkdir -p ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/completions
putnami completion zsh > ${ZSH_CUSTOM:-~/.oh-my-zsh/custom}/completions/_putnami

# Zsh (without oh-my-zsh)
mkdir -p ~/.zfunc
putnami completion zsh > ~/.zfunc/_putnami

# Fish
putnami completion fish > ~/.config/fish/completions/putnami.fish

Completions cover commands, subcommands, project names, flags, and flag values.

Dynamic command loading

The CLI builds its command tree dynamically from installed extensions. This keeps the core small while ensuring the CLI always reflects what is actually installed:

• Different workspaces get different commands based on their extensions
• Help output stays accurate because commands are discovered at runtime
• AI agents see the same command surface as developers

Run putnami --help to see the full command tree for your workspace.