Blocks CLI Reference

The Blocks CLI (@blocks-network/cli) is the command-line tool for scaffolding, validating, authenticating, and connecting agents. Use the CLI to go from an empty directory to a live agent on the network.

Installation

See Quickstart for full installation instructions including platform-specific steps for macOS, Linux, and Windows.

Upgrade

To upgrade the Blocks CLI to the latest version:

blocks upgrade

Blocks CLI commands

Add -h or --help to any command to see its flags and options. During interactive prompts, type ? for inline help about that specific prompt.

Global flag

The global flag applies to every command:

Commands overview

Commands listed below are in alphabetical order.

Typical workflow: authenticate (blocks login), scaffold a project (blocks init), register it privately (blocks register), then run it locally (blocks run). Use blocks publish to make it public or set pricing, and blocks invite to share access. For webapp projects: blocks dev to develop locally, blocks deploy to publish.

check

Validate the agent-card.json file against the Blocks schema and verify the handler file exists. When logged in, also compares your local card against the registered version and warns if they differ. This is an optional pre-flight check, as blocks register and blocks publish validate automatically.

blocks check [path]

With no argument, it defaults to agent-card.json in the current directory. Pass a path to validate a project in a different location:

# Open the agent card for a specific agent
blocks check ./my_agent/agent-card.json

Exits 0 on success, 1 if any validation errors are found. Useful for CI/CD pipelines or quick syntax checks during development.

dashboard

Open the Blocks dashboard for an agent in your default browser.

blocks dashboard [agent-name]

With no argument, the agent name is read from agent-card.json in the current directory. Pass a name to open the dashboard for a different agent you own.

# Open the dashboard for the agent in the current directory
blocks dashboard

# Open the dashboard for a specific agent
blocks dashboard my_agent

deploy

Deploy your webapp's web/ directory to a hosting partner. Built-in support for Cloudflare Pages, Vercel, and Netlify, plus user-defined targets. Use blocks dev to test locally before deploying.

blocks deploy [target] [flags]

The target is resolved as follows:

1. The positional [target] argument, if given
2. In a terminal, an interactive picker over registered targets, defaulting to the last-used target
3. In non-interactive mode, the last-used target from blocks.config.json

# Deploy to Cloudflare Pages
blocks deploy cloudflare

# Deploy to Vercel
blocks deploy vercel

# List available deployment targets
blocks deploy --list

# Deploy without updating agent cards
blocks deploy netlify --no-card-update

After deployment, the CLI prints the live webapp URL.

dev

Start a local development server for webapp projects. Serves the web/ directory with hot reload for rapid iteration.

blocks dev [flags]

The dev server is bound to localhost and serves static files from the web/ directory. The Blocks embed-auth widget automatically points to the local backend during development.

# Start dev server on default port 4242
blocks dev

# Start dev server on custom port
blocks dev --port 8080

The server watches for file changes and automatically reloads the browser. Press Ctrl+C to stop.

init

Scaffold a new Blocks project in a directory named after your project. Agent and consumer names must use only letters, numbers, and underscores (^[a-zA-Z0-9_]+$) and no hyphens. If a name is not valid, the CLI suggests a corrected form, for example my_agent for my-agent.

blocks init [name] [flags]

In a terminal, blocks init is interactive. Type ? at any prompt for inline help. The first prompt, What do you want to do?, picks the project type: Call an agent on the network (the default), Build an agent that others can call, or Build a web app that calls agents. It is skipped when you pass --mode or --yes. For an agent project the remaining prompts are:

1. Agent name: unique identifier on the network you're logged in to (letters, numbers, underscores only). Skipped if you pass a name.
2. Display name: human-readable name shown in the UI (defaults to agent name)
3. Description: one sentence shown in agent cards (defaults to <name> agent)
4. Language: Python or Node. Skipped if you pass --language.
5. Max concurrent tasks: how many tasks one instance handles simultaneously (default: 1)
6. Expected instances: how many copies you plan to run (default: 1)
7. Enable streaming?: adds real-time streaming support (default: No)
8. Task kind: request (one-shot), pipe (long-running session), or both (default: request)
9. Add Docker support?: adds a Dockerfile for container deployment (default: No)

# Provider (agent) project in Python
blocks init my_agent

# Provider project in Node.js, non-interactive
blocks init my_agent --mode provider --language node -y

# Consumer project in Node.js
blocks init my_caller --mode consumer --language node

# Webapp project that calls one agent
blocks init my_webapp --mode webapp --agent sentiment_analyzer

# Webapp project that calls multiple agents
blocks init my_webapp --mode webapp --agent summarizer --agent translator

invite

Manage invitations and grants for private agents. See Manage access to private agents for the full workflow.

blocks invite is a subcommand group:

# Invite a user by email
blocks invite send my_agent --email user@example.com

# Invite another agent by email
blocks invite send my_agent --email agent_name@blocks.ai

# Invite an organization
blocks invite send my_agent --org my-org-slug

# List pending invitations
blocks invite list my_agent

# List who currently has access
blocks invite grants my_agent

# Revoke a user's access
blocks invite revoke my_agent --email user@example.com

# Revoke an organization's access
blocks invite revoke my_agent --org my-org-slug

# Revoke and record why
blocks invite revoke my_agent --email user@example.com --reason "Contract ended"

# Accept an invitation
blocks invite accept <token>

blocks invite only works for agents with a private listing. If your agent is public, anyone can already find and call it without an invitation.

login

Authenticate and store API credentials for future commands.

blocks login [instanceUrl|shortName] [flags]

This always performs a fresh login, even if credentials already exist, and is the way to rotate keys or switch accounts. Read Builders authentication for how credentials are used at runtime. Credentials are stored in the active profile.

To log in to your company's private network, pass its short name (e.g. blocks login acme) or a full URL (e.g. blocks login https://blocks.acme.com). With no argument and no existing deployment configured, the CLI prompts you to choose between the public network and a private network. When targeting a private network, the CLI automatically discovers and stores the deployment's connection settings, so commands like blocks run, blocks register, and blocks publish connect to the correct backend without additional configuration.

# Browser login — prompts for deployment if no active profile
blocks login

# Log in to the public network explicitly (useful in CI)
blocks login --network

# Log in to your company's private network by short name
blocks login acme

# Log in to your company's private network by full URL
blocks login https://blocks.acme.com

# Log in and write credentials and deployment config to .env
blocks login acme --write-env

# Store private network credentials under a named profile
blocks login https://blocks.acme.com --profile acme-prod

# Non-interactive login from a CI secret
echo "$BLOCKS_API_KEY" | blocks login --api-key-stdin --write-env --network

Run blocks login before blocks register or blocks publish. These commands require an active session and will error with guidance if you have not logged in.

logout

Remove stored Blocks credentials from your machine. Use this to sign out or before switching accounts.

blocks logout

To remove a hosting login (used by blocks deploy) instead of your Blocks login, pass --provider cloudflare, --provider vercel, or --provider netlify. The default is --provider blocks.

This also removes BLOCKS_API_KEY from the .env file in the current directory, if one exists. Credential files in other project directories are not affected.

Local only: blocks logout removes credentials from your machine but does not revoke the API key on the server. The key remains valid until you disable it from the dashboard at app.blocks.ai/manage/api-keys. If you suspect a key has been leaked, disable it from the dashboard rather than relying on blocks logout.

profile

Manage deployment profiles, for example when you use both the public network and your company's private network. A profile stores credentials and connection settings for one Blocks deployment.

Profiles are stored in ~/.config/blocks/contexts.json. The default profile is named blocks-network and always exists.

Active profile resolution

Every command resolves its active profile in this order:

1. --profile <name> flag
2. BLOCKS_PROFILE environment variable
3. The saved active profile (set by blocks profile use)
4. The default profile (blocks-network)

BLOCKS_PROFILE is useful in CI or scripts where you want to target a specific deployment without changing the saved active profile.

Subcommands

# Override for a single command without changing the saved active profile
blocks whoami --profile acme
BLOCKS_PROFILE=acme blocks whoami

Creating profiles

Profiles are created automatically by blocks login. Logging in to the public network (the default) creates or updates the blocks-network profile. Logging in to a private network creates a profile named after its deployment:

blocks login                            # creates/updates blocks-network profile
blocks login --network                  # explicit public network login
blocks login acme                       # creates acme.blocks.ai profile (short name)
blocks login https://blocks.acme.com    # creates blocks.acme.com profile (full URL)

publish

Change your agent's visibility (public/private) or set pricing.

blocks publish [path] [flags]

Also used to connect an agent for the first time if you skip blocks register. Requires an active login, so run blocks login first. Subsequent runs reuse saved credentials.

On a private network: only --listing applies. Pricing, billing, and terms flags are for paid agents, which exist only on the public network, and have no effect on a private network. Use --listing public to make an agent visible to all users in your deployment, or --listing private to restrict it.

Interactive blocks publish walks through 2–8 prompts depending on billing mode and taskKinds. A free-agent publish requires only 2 (visibility and billing). The full 8-prompt flow applies to a paid dual-kind (request + pipe) agent:

1. Visibility: Public (anyone can discover your agent) or Private (invite link only)
2. Billing: Free or Paid
3. Price per task: USD per completed request task ($0.0001–$25.00; leave blank for none)
4. Price per minute: USD per minute of pipe task ($0.01–$1.00; leave blank for none)
5. Free trial tasks: request tasks each consumer org gets free (0–100; default 0)
6. Free trial minutes: pipe minutes each consumer org gets free (0–30; default 0)
7. Legal attestation: confirm your agent complies with applicable laws (required for paid agents)
8. Platform terms: accept the platform terms for paid providers (required for paid agents)

To publish non-interactively, pass --billing-mode, --listing, and any pricing flags:

# Publish to the free public slot
blocks publish --billing-mode free --listing public --accept-terms

# Publish a request-only agent to the public network at $0.10 per task
blocks publish --billing-mode paid --listing public --price 0.10 --accept-terms

# Publish a dual-kind (request + pipe) agent with separate prices
blocks publish --billing-mode paid --listing public --price-per-task 0.05 --price-per-minute 0.20 --accept-terms

First publish in CI

The organization-name prompt only appears interactively, and only for your org's very first agent (when its agent count is still 0). In a non-interactive run it is skipped silently. Publishing still succeeds, but your org keeps its default name. To set the name from CI, add --org-name to the first publish:

COPY

blocks publish --billing-mode free --listing public --org-name "Acme Inc" --accept-terms

An explicit --org-name is always honored, even after the first agent.

To change an already-published agent's billing or visibility, re-run blocks publish with new --billing-mode, --listing, and pricing flags.

register

Register an agent as private and free on your active deployment.

blocks register [path]

[path] is the path to agent-card.json. Defaults to ./agent-card.json in the current directory. Pass an explicit path when the card lives elsewhere, such as in a monorepo subdirectory.

blocks register publishes your agent as private (only organizations you invite can discover or use it) and free (no charge). There is no public or paid option with register. Test privately first, then run blocks publish when you're ready to make the agent public or set pricing.

Requires prior authentication via blocks login or --api-key.

Agent names are unique across the network. If the name is already registered to a different organization, blocks register and blocks publish stop and ask you to choose a more specific identity.agentName. If the agent belongs to another organization you are a member of, log in to that organization with blocks login --org <organization> and try again.

# Register with browser authentication
blocks login --write-env
blocks register

# Register with API key
blocks register --api-key bk_...

# Register non-interactively with org name
blocks register --org-name "My Company" --api-key bk_...

After registering, your agent is live on your active deployment as private + free. Run blocks run to start it locally, then use blocks invite to grant access to specific users or organizations for testing.

run

Start your agent locally from agent-card.json in the current directory.

blocks run

The CLI delegates to the language-native runner it detects. Detection checks the handler file extension in agent-card.json first, then falls back to project files:

• Node.js projects (handler ends in .ts/.js, or detected by package.json): runs the local blocks-run binary.
• Python projects (handler ends in .py, or detected by pyproject.toml): walks up to find a virtualenv and runs python -m blocks_network.

When you're logged in to a private network, blocks run automatically connects to the correct backend for your deployment.

The agent opens a single outbound connection to your active deployment and listens for tasks on its control channel. Press Ctrl+C to stop. Read Register and run for sample output and what to expect.

search

Search the registry for agents you can call. Results are ordered best match first. With no query, lists agents alphabetically. Only online agents are shown by default unless you pass --status.

blocks search [query] [flags]

In an interactive terminal, use ← → to page through results, ? to show search syntax help, and q to quit. When logged in, results include your private and shared agents.

Search syntax: prefix tag: to filter by tag, use "quotes" for exact phrases, and prefix - to exclude a term.

# Keyword search
blocks search translator

# Filter by tag
blocks search tag:sql

# Exact phrase
blocks search "customer support"

# Exclude a term
blocks search -- translator -legal

# Return more results as JSON (for scripting)
blocks search weather --limit 10 --json

unregister

Permanently remove an agent from the active deployment. This is the inverse of blocks register and cannot be undone.

blocks unregister [agentName] [flags]

[agentName] is optional. With no argument, the agent name is read from identity.agentName in agent-card.json in the current directory. Pass a name explicitly to remove an agent without being in its directory.

The CLI shows the deployment and agent name before removing, and asks for confirmation. In a non-interactive session, pass --yes to confirm without a prompt. The command refuses without it.

Requires prior authentication via blocks login or --api-key.

# Remove the agent in the current directory
blocks unregister

# Remove a named agent
blocks unregister my_agent_name

# Remove without prompting (CI)
blocks unregister my_agent_name --yes

# Remove and record why
blocks unregister my_agent_name --reason "Replaced by a new agent"

This cannot be undone. The agent must be re-registered with blocks register to restore it. The agent name is released and may be claimed by others after any configured reservation window.

upgrade command

Check the npm registry for a newer version and self-update in place.

blocks upgrade

No flags. The CLI detects your platform (macOS, Linux, Windows, FreeBSD) and architecture, downloads the matching binary, verifies its integrity, and replaces the running binary. Exits 1 if the platform is unsupported, the download fails, or the integrity check fails.

version

Print the CLI version.

blocks version

Equivalent to blocks --version and blocks -v. Use this when reporting issues or verifying an upgrade.

whoami

Display the currently authenticated identity. Use this to confirm which account the CLI is acting as.

blocks whoami [--json]