arc blocklet

arc blocklet covers a blocklet's whole lifecycle: scaffolding a new package, building it, validating it, and deploying it, either on its own or as part of a fleet.

Captured against arc 2.0.0-beta.50 (commit a99fb2c37, main, 2026-09-11). Run arc --version before you copy dumps; the commit is what pins the command surface.

arc blocklet <subcommand> [options]

Global flags (see Overview): --json, --view, --instance / -i (which local ARC instance; omit for default), and --home (instance root; to pick which instance, use --instance).

Scaffold

arc blocklet create

Scaffold a new blocklet package. Aliased as arc blocklet init (kept for backwards compatibility).

Usage

arc blocklet create [dir] [options]

--name must derive a legal blocklet identifier — checked, and rejected, before anything is written to disk:

$ arc blocklet create bad-dir --name "Not A Valid Name!"
ERROR: Error: Cannot derive a blocklet DID from --name "Not A Valid Name!": a blocklet identifier allows alphanumeric, hyphen, underscore only. Pass a valid identifier instead, e.g. --name Not-A-Valid-Name.

No bad-dir directory gets created. A valid name scaffolds normally, and prints a Next: hint for the next step in the pipeline:

$ arc blocklet create my-app --recipe basic
Created blocklet.yaml with did: "did:blocklet:my-app"
Next: arc blocklet build /path/to/my-app

The Next: chain follows the recipe's own capabilities: a DSL-bearing recipe (minimal-app, agent-workspace, support-community, agent, blog) inserts arc dsl validate before the build step, a manifest-only recipe (basic, blank) does not:

$ arc blocklet create my-agent --recipe minimal-app
Created minimal app blocklet "my-agent" with 18 file(s).
Next: arc dsl validate /path/to/my-agent

$ arc dsl validate /path/to/my-agent
Passed DSL validation
  path: /path/to/my-agent
  files: 16
Next: arc blocklet build /path/to/my-agent

$ arc blocklet build /path/to/my-agent
Published 20 file(s) → /path/to/my-agent/dist
  .afs/manifest.json  (http-mount protocol)
  blocklet.dist.json  (flat manifest)
  instance: requires /instance DID Space

Next: arc blocklet run /path/to/my-agent

Deploy to CF Pages:
  arc blocklet deploy /path/to/my-agent --project <project-name>

The Next: hint after a DSL-bearing scaffold is arc dsl validate, and that command does exit 0 on a fresh minimal-app. The rest of the DSL check chain is not uniformly green. With zero edits after arc blocklet create . --recipe minimal-app:

$ arc dsl lint .
Passed DSL lint
  path: /path/to/my-agent
  files: 16

$ arc dsl format --check .
Would format 0 file(s) (dry-run) — nothing to change
  path: /path/to/my-agent
  files: 5

$ arc dsl generate --check .
ERROR: Failed DSL generate (dry-run) — would change 4 file(s)
  path: /path/to/my-agent
  files: 11
  changed: .aup/app.json, .aup/pages/agent.json, .aup/pages/home.json, .aup/wrapper.json

  WARNING missing_man_coverage .aup/man/home.yaml: page "home" declares node-bound action(s) but has no .aup/man/home.yaml coverage
  ERROR generated_changed .aup/app.json: Generated artifact is stale. Run arc dsl generate --write.
  ERROR generated_changed .aup/pages/agent.json: Generated artifact is stale. Run arc dsl generate --write.
  ERROR generated_changed .aup/pages/home.json: Generated artifact is stale. Run arc dsl generate --write.
  ERROR generated_changed .aup/wrapper.json: Generated artifact is stale. Run arc dsl generate --write.

$ arc dsl doctor .
ERROR: Failed DSL doctor
  path: /path/to/my-agent
  decompile step: failed (0 files, 0 changed)

lint and format --check exit 0; generate --check and doctor currently exit 5. This is the CLI's current behavior on a zero-edit scaffold, not a documentation workaround — do not treat those two gates as green just because validate passed.

arc blocklet recipe

Discover the available scaffold recipes.

arc blocklet recipe <subcommand>

Example

$ arc blocklet recipe list
Blocklet scaffold recipes:
  basic
    Create only a blocklet manifest.
    capabilities: manifest
    generated files: 1
  ...
  minimal-app
    Create a tiny complete app with one web page, one AUP app, one agent, and generated settings.
    capabilities: web, aup, agent, settings
    generated files: 18
    source files: 14
  ...

$ arc blocklet recipe explain basic
Recipe: basic
  Create only a blocklet manifest.
  capabilities: manifest
  generated files:
    blocklet.yaml
  AFS data:
    blocklet.yaml
  checks:
    arc blocklet check <dir>

Build and validate

This repo's own build-and-check pattern (bun .claude/verify/config.ts) is arc blocklet check then arc blocklet build, run against blocklets/arcblock.

arc blocklet build

Build a Pages-ready dist/, copies files and writes .afs/manifest.json plus a flat manifest.

Usage

arc blocklet build [dir] [options]

On success it also prints a Next: arc blocklet run <dir> hint plus a Deploy to CF Pages: hint — see the full chain under arc blocklet create above.

arc blocklet check

Validate a blocklet against a recipe/profile contract. Aliased as arc blocklet validate.

Usage

arc blocklet check [dir] [options]

Unlike create and build, check does not print a Next: hint on success.

arc blocklet dev

Scan blocklet directory conventions and report the results, a lint pass over the directory shape rather than the DSL content (that's arc dsl lint).

arc blocklet dev [dir]

Inspect

arc blocklet list

List local blocklet packages: discovers blocklet.yaml, reports publish status.

arc blocklet list [dir]

arc blocklet inspect

Show the manifest and file list for a local blocklet package.

arc blocklet inspect <ref>

Run and deploy

arc blocklet run

Serve a single blocklet on the daemon and print its access URLs.

Usage

arc blocklet run <path> [options]

To keep a source across daemon restarts, record it on a named instance: arc service start --instance <name> --blocklet <path>. See arc service.

arc blocklet deploy

Publish a blocklet locally, then deploy it to Cloudflare Pages, in one step.

Usage

arc blocklet deploy [dir] [options]

arc blocklet instance

Manage blocklet instances, i.e. deployments.

arc blocklet instance <subcommand> [options]

Fleet

arc blocklet fleet deploys a group of blocklets as one aggregate Pages project, this is how a multi-domain site fleet (like this one) gets deployed together.

arc blocklet fleet <subcommand> [dir] [options]

Shared options across the fleet subcommands: --blocklets <list> (overrides --fleet), --fleet <yaml> (defaults to <dir>/site-fleet.yaml or <dir>/fleet.yaml), --deployment <id> (resolves the fleet manifest path from instances.json, mutually exclusive with --fleet), --project <name> (default afsd-blocklets), --domain-root <domain> (default afsd.io).

--deployment/--fleet is a declared, enforced conflict on all four subcommands (not just prose):

$ arc blocklet fleet deploy --deployment foo --fleet bar.yaml
ERROR: Arguments deployment and fleet are mutually exclusive
...

Passing only one of the two flags clears this specific check — it then fails later for a different, expected reason (no such fleet manifest here), which is how you tell the guard discriminates rather than rejecting everything:

$ arc blocklet fleet deploy --fleet bar.yaml
ERROR: Error: Fleet manifest not found: /path/to/bar.yaml