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

• <project> targets a specific project
• . targets the current project
• --impacted runs only what changed
• --all runs the whole workspace
• no target is equivalent to --impacted if the context is the workspace, . otherwise
• --projects <project-1>,<project-2> runs the command for the specified 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)
• --type <types> filter projects by type (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"],
  "type": "application"
}

Use filter flags to narrow which projects a job targets:

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

# Test only libraries
putnami test --all --type library

# 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 --type application

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"]
  }
}

Type inference from extensions

When a project does not explicitly set putnami.type, the type is automatically inferred from its active extensions. Extensions can declare a projectType in their putnami.extension.json, which is then assigned to every project where the extension is active. For example, @putnami/application declares "projectType": "application", so any project depending on it is automatically typed as application without extra configuration.

Explicit type in .putnamirc.json (or putnami.type in package.json) always takes precedence.

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.
• 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 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.
• putnami projects type <project> [type]: Manage project type.
  • No type: shows the current type.
  • With type: sets it (e.g., application, library).
  • --clear: removes the explicit type.

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.

Compiled Binary

The Putnami CLI can be compiled into a native executable using bun build --compile. The resulting binary embeds the Bun runtime and all SDK dependencies — no runtime installation is required to use it.

# Compile the CLI
bun build --compile ./core/cli/bin/putnami.ts --outfile putnami

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

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

Next steps

• Previous: Workspace overview
• Next: Jobs & commands