dome blueprint

dome blueprint <command>

Manage portable Agent Blueprints. Run shared verbs at dome blueprint <verb> to process every Blueprint in the current directory, or scope them with dome blueprint agent <verb> and dome blueprint workspace <verb>.

Project discovery and fan-out

The unscoped commands discover:

1. dome-workspace.yaml, when present
2. Agent Blueprints listed by dome-agents.yaml, in declaration order
3. Otherwise, the single dome-agent.yaml

Workspace runs before agents. Fan-out stops at the first failure. Unscoped commands do not accept --file; use a scoped command to select another path.

The shared fan-out verbs are:

validate  fmt  compile  diff  bind  assess  apply  status

Agent-specific top-level commands

init

dome blueprint init [agent-name] [--name <name>] [--file <path>] [--force]

Create an Agent Blueprint scaffold. The default file is dome-agent.yaml. If no name is supplied, the CLI derives one from the containing directory.

adopt

dome blueprint adopt <agent-id-or-name> [flags]

Read an existing workspace agent and write dome-agent.yaml plus its lockfile.

Key flags:

• --file, -f <path> — source path; default dome-agent.yaml
• --workspace <selector> — synced workspace UUID, name, alias, or shorthand
• --force — replace an existing source

run

dome blueprint run [flags] [-- command args...]

Alias: dome blueprint dev.

Assess one Agent Blueprint, check runtime preflight, and start its declared runtime. Arguments after -- replace the declared command for this run. run does not apply drift. Without --strict, non-operability drift produces a warning while the Gateway remains authoritative.

Key flags:

• --file, -f <path> — Agent Blueprint source
• --revision <path> — use a compiled Revision instead of compiling --file
• --bindings <path> — bindings file; default beside the source
• --workspace <selector> — target a synced workspace without switching context
• --env-file <path> — load an env file; repeatable
• --strict — block on any drift or failed check
• --provision-key — create or rotate the current user's development credential envelope
• --write-key-to <path> — write the provisioned DOME_AGENT_API_KEY to an env file; requires --provision-key
• --yes, -y — confirm credential provisioning without prompting

up

dome blueprint up [flags] [-- command args...]

Assess and reconcile the Workspace Blueprint first, then every Agent Blueprint. It can provision a credential and start exactly one runnable agent. Use --apply-only when a project has several agents, no declared runtime, or an application hosts the agents itself.

Key flags:

• --workspace <selector> — target synced workspace
• --env-file <path> — load an env file; repeatable
• --yes, -y — confirm reconciliation and key provisioning
• --no-wait — do not wait for a newly attached tool to appear in the observed Gateway catalog
• --strict — block the run on any Blueprint drift or failed check
• --provision-key — create or rotate the child credential envelope
• --write-key-to <path> — write the provisioned envelope to an env file; requires --provision-key
• --apply-only — reconcile and stop without requiring or starting a runtime

Shared lifecycle commands

The syntax below uses <scope> to mean agent or workspace. Omit the scope to fan out where noted.

validate

dome blueprint validate
dome blueprint <scope> validate [--file <path>]

Strictly parse and normalize source locally. This command does not call Dome or write a lockfile.

fmt

dome blueprint fmt [--check]
dome blueprint <scope> fmt [--file <path>] [--check]

Format source without changing its semantics. --check exits non-zero instead of writing when formatting differs.

compile

dome blueprint compile [--check]
dome blueprint <scope> compile [--file <path>] [--output <path>] [--check]

Compile deterministic, workspace-independent Revision lockfiles locally. Scoped --output, -o overrides the default sibling lockfile. --check verifies the committed lock without writing.

diff

dome blueprint diff
dome blueprint <scope> diff [left-lockfile right-lockfile] [--file <path>]

Show semantic changes. With no lockfile arguments, compare the sibling lockfile with the current source. Supply either zero or two lockfiles.

bind

dome blueprint bind [flags]
dome blueprint <scope> bind [flags]

Assess against a workspace and record resolved resource IDs for rebinding protection. --refresh acknowledges and replaces changed bindings.

Key flags:

• Fan-out: --workspace, --env-file, --refresh
• Scoped: --file, -f, --revision, --bindings, --workspace, --env-file, --refresh

assess

dome blueprint assess [flags]
dome blueprint <scope> assess [flags]

Resolve names and permissions and report constraints, checks, operations, and blockers without mutation.

Key flags:

• Fan-out: --workspace, --env-file, --check
• Scoped: --file, -f, --revision, --bindings, --workspace, --env-file, --check

--check exits with code 7 unless the assessment is satisfied.

apply

dome blueprint apply [flags]
dome blueprint <scope> apply [flags]

Assess, confirm, execute authorized operations in dependency order, and return the final observed assessment. Apply is not transactional and has no rollback across endpoints.

Key flags:

• Fan-out: --workspace, --env-file, --yes, -y, --no-wait
• Agent scope: --file, -f, --revision, --bindings, --workspace, --env-file, --yes, -y, --no-wait, --create-key <name>
• Workspace scope: --file, -f, --revision, --bindings, --workspace, --env-file, --yes, -y

--no-wait applies only to Agent Blueprints. By default, agent apply can wait up to 90 seconds when the only unresolved item is a newly attached tool that has not appeared in the Gateway's observed catalog.

Agent apply can register the agent, reconcile declared access and Rules, and optionally create a named credential envelope. Workspace apply is additive: it creates missing Gateways, verification providers, tool and model connections, pools, and attachments, but never edits or deletes an existing shared resource.

status

dome blueprint status [flags]
dome blueprint <scope> status [flags]

Report local lock freshness separately from live reconciliation and bindings. Agent status also checks runtime preflight and credential availability.

Key flags:

• Fan-out: --workspace, --env-file, --check, --strict
• Agent scope: --file, -f, --bindings, --workspace, --env-file, --check, --strict
• Workspace scope: --file, -f, --bindings, --workspace, --env-file, --check

--check exits with code 7 when not ready. --strict requires every Agent Blueprint constraint and check to be satisfied.

Workspace-only command

workspace init

dome blueprint workspace init [--file <path>] [--force]

Create a dome-workspace.yaml scaffold. --force replaces an existing source.

File and environment defaults

Commands that use workspace data accept repeatable --env-file. Earlier explicit files win over later files; process environment values win over every file. With no flag, the CLI searches upward from each source YAML directory to the Git repository root for the nearest .env.

All commands also support the global CLI flags, including --json, --quiet, --context, and --activity.

Next steps

• Agent Blueprints
• Blueprint MCP tools