Set up the workspace

putnami cloud setup links this repository to a Putnami Cloud workspace and provisions the workspace-local config the platform needs. Run it once per repository.

Deploying needs to know which Cloud workspace to deploy into. Setup records that link in your manifest (safe to commit) and, at the same time, turns on the remote build cache and registry credentials and installs the managed Putnami Intelligence MCP and portable audit workflow.

putnami cloud setup

With no arguments, setup creates a new workspace (named from your putnami.workspace.json / putnami.json name) and links it. To link an existing workspace instead, pass its id:

putnami cloud setup --workspace <workspace-id>
Want to… Do this
Link an existing workspace putnami cloud setup --workspace <id>
Name a new workspace putnami cloud setup --workspace-name "<name>"
Target a non-default environment putnami cloud setup --environment <env>
Skip the build cache putnami cloud setup --no-cache
Disable Intelligence and audit putnami cloud setup --no-intelligence
Keep Intelligence but disable audit putnami cloud setup --no-audit
Override the Intelligence graph slug putnami cloud setup --intelligence-workspace <slug>
Adopt a conflicting audit workflow putnami cloud setup --force-audit
Record the repository URL putnami cloud setup --repository <url>

What setup writes

File Purpose Commit it?
putnami.workspace.json → options.@putnami/cloud.workspace the workspace id (and control-plane URL if non-default) yes
putnami.workspace.json → options.@putnami/cloud.intelligence explicit Intelligence/audit enablement and graph workspace slug yes
.AI/skills/audit, .agents/skills/audit, .claude/skills/audit managed portable audit workflow and agent adapters yes
.mcp.json, .codex/config.toml shared putnami mcp wiring (run_jobs remains prompted) yes
.AI/domains.json deterministic project-domain grouping, only generated when absent yes
.putnami/cache.json remote build cache config — a token source, never a raw bearer yes
.putnami/cloud-link.json local mirror of the link no (local cache)

The committed link is intentionally minimal: just enough to connect the repository to its workspace. Everything else is resolved from the control plane at use time.

Setup requires a freshly logged-in session carrying intelligence.audit before it changes repository files. If an older session lacks the scope, rerun putnami cloud login. Opting out records disabled feature flags and never deletes workflow files installed by an earlier setup.

Ensure mode for automation

--auto makes setup idempotent and non-failing: it configures Cloud only when the repository is already linked and you are already signed in, never creates a workspace, and never breaks the surrounding command. This is the mode the extension's install hook uses.

putnami cloud setup --auto

Verify

putnami cloud config --schema     # the resolved config schema for a project
putnami cloud whoami              # the active identity

Next