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 package .            # Create distributable artifacts
putnami publish .            # Publish a package
putnami deploy my-app        # Deploy through a deployer extension
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
P	publish
d	deploy
D	deploy

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 --global — Upgrade the global CLI in ~/.putnami/bin instead of the workspace pin; runs anywhere (no workspace required) and implies --cli
• putnami upgrade --extensions — Only upgrade extensions and templates
• putnami upgrade --deps — Only upgrade framework dependencies
• putnami upgrade --channel canary — Upgrade to the latest canary release set
• putnami upgrade --branch feature-x — Upgrade to the latest release set published for a branch tag
• putnami upgrade --version 1.2.3 — Upgrade to an exact Putnami release version
• putnami upgrade --dry-run — Resolve and print the plan without changing files

Flags can be combined. When no flags are given, all phases run against the stable channel. The legacy --putnami-version flag remains as an alias for --version. See the Upgrade Putnami guide for details. Branch upgrades select tags created by putnami publish --also-branch-tag; publish and upgrade both normalize branch names, so feature/foo maps to feature-foo.

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 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 get — Show the effective workspace, scope, or project release version
• putnami version set <version> — Set the explicit release version
• putnami version bump <patch|minor|major> — Bump the selected release version
• putnami version tag — Create an annotated git tag for the selected release version (--push to push it)

All four accept --scope <path> or --project <selector> to target a scope or project instead of the workspace. To update installed CLI binaries, use putnami upgrade --cli (workspace pin) or putnami upgrade --global.

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 (otherwise resolves workspace baseline, upstream, origin/HEAD, then local main/master)

Default behavior

When no target is given:

• Feature branches — targets projects impacted vs trunk (origin/HEAD, origin/main, then local main/master)
• main/master with a local same-command/params marker — targets projects impacted vs that marker SHA
• main/master with no local marker and an active remote-cache run marker — targets projects impacted vs the remote marker SHA, if that SHA resolves locally
• main/master with no usable marker — targets all projects

Use . when you want current-directory scope instead of the smart default.

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 <mode|n>	Parallelism policy (auto, eco, max) or explicit worker count
--retry <n>	Retry transient failures

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.

The --output=jsonl stream follows the session stream contract defined by the runtime protocol (protocols/runtime/schemas/stream.json): job:start / job:event / job:end envelopes per job, closed by one session:end aggregate. See protocols/runtime/doc/04-output-contract.md for the full contract.

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

putnami upgrade --cli refreshes the installed completion file for your current shell. For zsh, clear the completion cache after an upgrade if completions still look stale:

rm -f ~/.zcompdump*
exec zsh

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.