commands.md

Command reference

The root manifest owns command definitions; Turbo configuration owns task dependencies and caching. Package manifests own the scripts that Turbo invokes.

Command	Purpose	Notes
pnpm dev	Run package watch tasks	Persistent and uncached
pnpm build	Build all packages	Produces package dist/ directories
pnpm typecheck	Type-check package sources and tests	Depends on upstream builds
pnpm test	Run documentation, release, source, CLI/action, and installed-package tests	Artifact suites build their dependencies
pnpm test:e2e	Run the built CLI and action against real template fixtures	Builds tested packages and dependencies; does not contact AWS
pnpm test:packages	Install local package archives and verify public entry points	Builds packages; requires public npm access; uncached; never publishes
pnpm lint	Check package source and tests with Biome	Read-only
pnpm lint:fix	Apply Biome fixes	Mutates files and is uncached
pnpm docs:check	Check the repository knowledge system	Validates links, fragments, aliases, reachability, and entry points
pnpm docs:test	Test the documentation and owning-pages checker CLIs	Uses dependency-free node:test fixtures
pnpm release:test	Test changelog lookups, GitHub links, and selective release recovery	Uses synthetic HTTP responses and temporary local Git remotes; never publishes packages
pnpm exec turbo boundaries	Enforce cli/action -> sdk -> rules	This is the supported boundary command
pnpm verify:repo	Run documentation checks/tests, release tests, and package boundaries	Always runs repository checks; no affected-package filtering
pnpm verify:packages	Run package lint, typecheck, source, E2E, and installed-package tests	Turbo owns dependencies; accepts --affected and --concurrency
pnpm verify	Run repository checks followed by package verification	Full local gate; forwards flags such as --affected to package tasks
pnpm clean	Remove package build output	Destructive only to generated dist/ output
pnpm depupdate	Update the pnpm pin and dependencies	Mutates manifests and the lockfile

Discovery timeout

cloudburn discover --timeout <seconds> sets the total discovery deadline (default: 300 seconds). The value must be an integer from 1 to 2147483. An expired deadline stops AWS work and exits with code 2. SDK callers can set timeoutMs and provide an AbortSignal to CloudBurnClient.discover().

Discovery evidence cache

Option	Default	Behavior
--cache normal	normal	Reuse fresh, complete evidence; load missing or expired evidence. Rules and configuration are evaluated on every run.
--cache refresh		Collect current evidence without falling back to cached evidence if collection fails. Only complete successful loads replace entries.
--cache off		Bypass persistent evidence reads and writes.
--cache-dir <path>	$XDG_CACHE_HOME/cloudburn/evidence, or ~/.cache/cloudburn/evidence	Select local persistent storage for normalized AWS evidence and independent public pricing artifacts.
--cache-context <id>	Temporary AWS credential session scope when derivable	Identify the effective authorization and session-policy revision. Change this value when those permissions change; an account ID or role ARN alone is insufficient.

The default uses $XDG_CACHE_HOME only when it is an absolute path; an empty or relative value falls back to ~/.cache/cloudburn/evidence.

Without a safe temporary credential scope or an explicit context, customer evidence reuse is disabled. Public pricing can still be reused independently. Cache entries never include credentials. --cache off also disables public pricing persistence. A cache read does not prove AWS discovery coverage: source delays and unknown resources remain visible through evidence completeness, coverage, and diagnostics.

Table output summarizes cached and newly collected evidence, incomplete entries, and the oldest observation timestamp. JSON output preserves the full evidence array, including collection and observation times, cache source, and coverage. Freshness TTLs are tunable starting policies, not measured optimal defaults; use the SDK cache options to tune them, or --cache refresh when a run needs newly collected evidence. See the SDK README for freshness policies and configured SDK reuse.

Turbo filters

pnpm turbo run build --filter @cloudburn/sdk
pnpm turbo run test --filter cloudburn...
pnpm turbo run lint --filter ...[main]

Package layer tags live in each package's turbo.json, not its package.json. Root turbo.json maps those tags to denied dependency directions and defines task caching: cloudburn is layer:cli, @cloudburn/action is layer:action, @cloudburn/mcp is layer:mcp, @cloudburn/vscode is layer:vscode, @cloudburn/sdk is layer:sdk, and @cloudburn/rules is layer:rules.

build depends on upstream builds and caches dist/**; its inputs exclude test/** because fixtures do not affect published output. typecheck depends on upstream builds. Source test tasks use the test:inputs transit task to inherit upstream source hashes without waiting for builds or upstream tests. test:e2e and test:package depend on the current package build. test:package is uncached because it installs archives with public registry dependencies. dev is persistent and uncached, while lint:fix and clean are uncached because they mutate or remove files. Changes to tsconfig.base.json, biome.jsonc, pnpm-lock.yaml, or the root package.json invalidate the shared task cache.

The VS Code package overrides build inputs to include its editor test bundle and the root license. Its build stages the public extension manifest, runtime bundle, and listing assets in dist/vscode/, all cached inside dist/**. Its uncached E2E task loads that generated directory in a real editor. package:vsix depends on the build, packages the same directory, and writes dist/cloudburn.vsix; it requires vsce on PATH and neither publishes nor installs the extension.

Release-only commands

pnpm changeset:version and pnpm release mutate versioned artifacts or publish packages. They are reserved for the automated release flow or explicit maintainer operations; do not run them during normal feature work. See the release guide.