CLI

The Putnami CLI is the control center for your workspace. It abstracts the complexities of the underlying tools and provides a consistent interface for developers, CI/CD systems, and AI agents.

Common commands

$ putnami build <my-project>   # build a specific project
$ putnami test                 # test only what changed depending on the context (workspace, project)
$ putnami lint --all           # lint the whole workspace
$ putnami deploy .             # deploy the whole workspace
$ putnami serve <my-app>       # serve a specific app and all the runnable dependencies
$ putnami lint,test,build      # lint, test and build for all impacted projects

Targets

The CLI supports multiple ways to select which projects a command runs on.

Target expressions

Target expressions use project IDs (path-based) to select projects:

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

Every project has a canonical ID computed as "/" + path relative to the workspace root (e.g. /typescript/frameworks/web). Use putnami projects list to see all project IDs.

Aliases and groups

Define shortcuts in .putnamirc.json for frequently used targets:

{
  "projectAliases": {
    "web": "/typescript/frameworks/web",
    "cli": "/tooling/cli"
  },
  "groups": {
    "frontend": "/typescript/frameworks/web,/typescript/frameworks/ui",
    "all-go": "/go/..."
  }
}

Aliases and groups can also be defined in intermediate (breadcrumb) .putnamirc.json files at any directory level.

Flags

• . targets the current project, or all projects under the current directory if not inside a project
• --impacted runs only what changed
• --all runs the whole workspace
• --projects <project-1>,<project-2> runs the command for the specified projects

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

Global flags (available on every command)

• --help, -h show help and exit
• --version, -v, -V show the CLI version and exit
• --output=<format> set output format: text (default), json (single summary object), jsonl (streamed events + summary line), or cloud-logging (Google Cloud Logging structured JSON, auto-detected on Cloud Run)
• --quiet, -q suppress non-error output
• --no-color disable color output
• --color force color output

Environment variable equivalents are supported for global output options, e.g. PUTNAMI_OUTPUT=json, PUTNAMI_QUIET=true, PUTNAMI_COLOR=true, PUTNAMI_NO_COLOR=true, and NO_COLOR.

Common job flags (project/workspace jobs)

These flags are exposed by the base job option classes and apply to most job commands:

• --all run the job on all projects
• --impacted run the job on git-impacted projects
• --projects <list> run the job on a comma-separated list
• --dry-run show changes without applying them (when supported)
• --skip-ci skip execution when CI=true
• --verbose show job results and important diagnostics (disables spinner)
• --debug stream all job events in real-time — phases, logs, progress (implies --verbose behavior)
• --install install/prepare the job on the project when possible
• --tag <tags> filter projects by tag (comma separated)
• --exclude-tag <tags> exclude projects by tag (comma separated)
• --exclude <names> exclude projects by name (comma separated)
• --no-cache skip reading from cache (still writes results). Use putnami cache clean to delete cached data
• --max-parallel <n> cap concurrent jobs (0 = unlimited)
• --watch, -w watch for file changes and re-run affected jobs

Project Filtering

Projects can declare metadata in .putnamirc.json (or in package.json under the putnami key for TypeScript projects):

{
  "name": "@myorg/my-app",
  "tags": ["frontend", "deployable"]
}

Use filter flags to narrow which projects a job targets:

# Build only frontend projects
putnami build --all --tag frontend

# Build everything except a specific project
putnami build --all --exclude legacy-app

# Exclude projects by tag
putnami test --all --exclude-tag e2e

# Run only e2e tests (overrides workspace excludeTags)
putnami test --tag e2e

# Combine filters: deployable backend services
putnami build --all --tag backend,deployable

Filters are applied after project resolution (--all, --impacted, etc.), so they narrow the selected set rather than replacing it.

Workspace-level tag exclusion

Tags listed in .putnamirc.json under disable.tags are automatically excluded from all project selections by default. Use --tag to explicitly include projects with those tags:

{
  "disable": {
    "tags": ["e2e"]
  }
}

Help system

The CLI features an enhanced help system that organizes commands by category. Running putnami --help groups commands into logical sections:

• Build & Compile — build, lint, format, and other build-related commands
• Testing — test and related commands
• Deployment — deploy and related commands
• Workspace Management — workspace, deps
• Project Management — projects
• Extensions — extensions
• Utilities — completion, telemetry

Each command's help output includes:

• Examples — usage examples (defined on the command or generated as fallbacks)
• Related Commands — links to related commands (e.g., workspace shows projects list and extensions list)
• See Also — additional documentation references
• Flags grouped by category — common, project, execution, output, and advanced

Both --output=text (default) and --output=json are supported. JSON output includes the same structured data: category, related commands, see also, and grouped subcommands.

Global Commands

These commands are available in every Putnami workspace.

putnami deps (Dependency Manager)

Manages workspace dependencies.

• putnami install: Installs workspace dependencies across active technologies. When an extension name is provided (for example putnami install @putnami/go), it downloads and installs that extension from purnami.dev.
• putnami deps install: Installs dependencies and runs extension workspace installers (for example Bun install + Python UV lock sync).
• putnami deps add <pkg>: Adds a package to the workspace.
• putnami deps remove <pkg>: Removes a package from the workspace.

Related: workspace init, projects list

putnami extensions (Extension Manager)

Manages the extensions installed in your workspace.

• putnami extensions list: Lists all active extensions and their status.
• putnami extensions describe <extension>: Shows detailed information about an extension, including its jobs and commands.
• putnami extensions install <extension>: Downloads from purnami.dev, unpacks, and registers an extension under .putnami/extensions/.
• putnami extensions reset: Resets the extension registry, useful if the configuration gets out of sync.

Related: workspace describe, projects list

putnami workspace (Workspace Management)

Commands for managing the workspace configuration itself.

• putnami workspace init: Initializes a new Putnami workspace in the current directory.
  • --project <name>: Scaffold an initial project during workspace creation.
  • --project-path <path>: Place that initial project somewhere other than the default packages/<project-name>.
• putnami workspace describe: specific details about the current workspace configuration.

Related: projects list, extensions list

putnami config (Configuration Management)

Manages CLI configuration files (.putnamirc.json) at different scopes (global, workspace, local).

• putnami config show: Shows the current merged configuration. Use -g/-w to show a specific scope, or pass a command name to see its effective config.
• putnami config set <key> <value>: Sets a configuration value. Supports dot-notation paths (e.g., commands.build.parallel). Use -g/-w to target a scope.
• putnami config validate: Validates configuration files for correctness. Use -g/-w to validate a specific scope.
• putnami config setup: Creates a default .putnamirc.json file. Use -g/-w to target a scope.

putnami scopes (Scope Management)

Inspect workspace scopes — the intermediate organizational layer between the workspace and projects.

• putnami scopes list: Lists all scopes with their project counts, tags, groups, and aliases.

Supports --output=jsonl for machine-readable output.

Related: projects list, projects sync, workspace describe

putnami projects (Project Management)

Manages the individual projects (apps/libraries) within the workspace.

• putnami projects list: Lists all projects in the workspace.
• putnami projects create <name> [--template <name>]: Scaffolds a new project, optionally from a template.
• putnami projects describe <project>: Shows details for a specific project.
• putnami projects tag <project> [tags]: Manage project tags.
  • No tags: lists current tags.
  • With tags (comma-separated): adds them.
  • --remove: removes the specified tags.
  • --set: replaces all tags with the specified ones. Related: workspace describe, deps install

Project Templates

Templates let you scaffold a fully configured project in one command. Each language extension ships its own templates:

Template	Extension	Description
typescript-web	@putnami/typescript	React SSR web app with file-based routing, layout, and client components
typescript-server	@putnami/typescript	HTTP server with @putnami/application, file-based routing, and tests
typescript-library	@putnami/typescript	TypeScript library with exports and tests
go-server	@putnami/go	HTTP server with net/http, JSON endpoint, and tests
go-library	@putnami/go	Go library with exported function and tests
python-server	@putnami/python	FastAPI server with uvicorn and tests
python-library	@putnami/python	Python library with importable module and tests

# TypeScript
putnami projects create my-app --template typescript-web
putnami projects create my-api --template typescript-server
putnami projects create my-lib --template typescript-library

# Go
putnami projects create my-api --template go-server
putnami projects create my-lib --template go-library

# Python
putnami projects create my-api --template python-server
putnami projects create my-lib --template python-library

Options:

• --template <name>: Template to scaffold from.
• --template-extension <ext>: Restrict template lookup to a specific extension (e.g., @putnami/typescript). Required only if template names conflict across extensions.
• --path <path>: Custom project path (default: packages/<project-name>).
• --install: Install dependencies after creation (same behavior as putnami deps install).

Template files ending in .template are processed with variable substitution (<%= projectName %>, <%= projectModule %>, <%= projectPath %>). Other files are copied as-is.

Command Aliases

The CLI supports command aliases — shortcuts that map to longer command paths. Aliases save keystrokes and let teams define workspace-specific shortcuts.

Built-in Aliases

These aliases are registered automatically:

$ putnami b .           # same as: putnami build .
$ putnami t --all       # same as: putnami test --all
$ putnami l --impacted  # same as: putnami lint --impacted
$ putnami s my-app      # same as: putnami serve my-app
$ putnami f .           # same as: putnami format .
$ putnami p .           # same as: putnami publish .
$ putnami init          # same as: putnami workspace init

Custom Aliases

Define your own aliases in .putnamirc.json at the workspace root:

{
  "aliases": {
    "ci": "lint,test,build",
    "dev": "serve",
    "deploy": {
      "target": "docker build",
      "description": "Deploy via Docker"
    }
  }
}

Run putnami --help to see all available aliases.

Dynamic Commands

Putnami builds the CLI dynamically from installed extensions. This keeps the core CLI small while letting each extension expose its own command group, flags, and help text.

Why it works this way

• Different workspaces need different tooling (docker, python, go, deploy, etc.).
• Extensions can ship jobs and commands together, so the CLI reflects what is actually installed.
• Help output stays accurate because commands are discovered at runtime.
• AI agents see the same command surface you do, so they can explore the workspace safely and run only what exists.

How it works

1. Extensions register commands and jobs in their putnami.extension.json.
2. The CLI loads extensions at startup and builds the command tree.
3. Each extension can contribute top-level commands or subcommands.

Examples

# See available command groups in this workspace
putnami --help

# Commands contributed by @putnami/python
putnami --help
putnami test --impacted

Run putnami --help or putnami <command> --help to see the commands available in your current workspace.

Binary

The Putnami CLI is a single static Go binary with zero external dependencies. No runtime installation is required.

# Install via the install script
curl -fsSL https://putnami.dev/install.sh | bash

# Or use the workspace wrapper (auto-builds from source)
./putnamiw build --impacted

The binary includes all built-in commands (workspace, projects, scopes, extensions, config, deps, cache, sessions, completion, telemetry, version). Extension commands are discovered at runtime from the filesystem.

Extensions that embed their CLI flags in putnami.extension.json work fully with the binary. See Extensions > Any-Language Extensions for manifest details, or follow the Create an extension how-to guide.

Shell Completion

The CLI provides tab-completion for commands, subcommands, project names, flags, and flag values. The install script (install.sh) sets up completions automatically. You can also configure them manually.

Automatic setup

When you install via curl -fsSL https://putnami.dev/install.sh | bash, the installer detects your shell and writes the completion script to the appropriate location:

Shell	Location
Zsh (oh-my-zsh)	${ZSH_CUSTOM}/completions/_putnami
Zsh (manual)	First writable user fpath dir, or ~/.zfunc/_putnami
Bash	~/.local/share/bash-completion/completions/putnami
Fish	~/.config/fish/completions/putnami.fish

Manual setup

Generate and install the completion script for your shell:

# 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
# Add to ~/.zshrc (before any compinit call):
#   fpath=(~/.zfunc $fpath)
#   autoload -Uz compinit && compinit

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

After installing, restart your shell (exec zsh, exec bash, or reopen your terminal).

What gets completed

• Commands — build, test, lint, serve, publish, format, plus extension-provided commands
• Structured commands — extensions, projects, scopes, workspace, deps, cache, config, completion
• Subcommands — e.g. putnami extensions <Tab> suggests install, list, remove, update
• Flags — --impacted, --all, --verbose, --output, etc.
• Flag values — --output <Tab> suggests jsonl, cloud-logging; --projects <Tab> suggests workspace project names

Watch Mode

The --watch flag enables continuous file-watching mode for any job command. When active, the CLI monitors the workspace for file changes, determines which projects and tasks are affected, and re-executes only what's needed.

# Watch and re-run tests on file change
putnami test . --watch

# Watch and re-lint on change
putnami lint . --watch

# Watch and rebuild affected tasks on change
putnami build . --watch

# Watch with serve (hot-reload)
putnami serve my-app --watch

Change detection

• Polling-based — file system is polled at 100ms intervals for maximum portability.
• 150ms debounce — rapid edits within 150ms are coalesced into a single batch.
• Smart filtering — .git/, node_modules/, .putnami/, dist/ are automatically ignored.

What re-runs

Only affected projects re-run, not the full plan:

1. Changed files are mapped to their containing projects.
2. Task inputs.*.files globs determine which tasks are affected.
3. The dependency graph propagates changes transitively — if a library changes, all dependent apps re-run too.

Serve mode

When used with serve, watch mode manages the server process lifecycle:

• Dependencies are rebuilt before restarting.
• The server receives SIGTERM for graceful shutdown (5s timeout), then SIGKILL.
• Server logs remain visible between restarts (the terminal is not cleared).

Next steps

• Previous: Workspace overview
• Next: Jobs & commands