CLI Command Reference

For AI agents: the documentation index is at llms.txt (full corpus: llms-full.txt). A markdown source for this page is /cli/commands.md.

Complete reference for the Arete CLI (a4).

---

Installation

Prebuilt, signed binary. No Rust toolchain or account required.

curl -fsSL https://arete.run/install.sh | sh        # macOS / Linux
irm https://arete.run/install.ps1 | iex             # Windows PowerShell
npx @usearete/a4 install                            # if you prefer npm (same as npm install -g @usearete/a4)

The bootstrapper downloads the release asset for your platform plus checksums.txt and its minisign signature, verifies the SHA-256 (and the signature when minisign is available), then hands off to a4 self install, which copies the binary to ~/.local/bin/a4 (%USERPROFILE%\.local\bin\a4.exe on Windows), writes ~/.arete/receipt.json, adds the directory to your shell profile, and prints these two lines last on stdout:

A4_BIN=/Users/x/.local/bin/a4
export PATH="$HOME/.local/bin:$PATH"

Shells that were already open captured PATH before the install. Use the A4_BIN path or run the export line in that shell. If another a4 is earlier on PATH (~/.cargo/bin/a4, an npm shim), the installer warns and names the file; it never deletes it.

Installer arguments (sh -s -- [VERSION] [--no-modify-path] [--install-dir DIR]):

Argument / variable	Description
VERSION, A4_VERSION	Install a specific version instead of the latest
--install-dir <DIR>, A4_INSTALL_DIR	Install directory (default ~/.local/bin; XDG_BIN_HOME is honoured)
--no-modify-path, A4_NO_MODIFY_PATH=1	Do not edit shell profiles or the Windows user PATH; CI also skips it

Then, in a project:

a4 init -y          # arete.toml, AGENTS.md block, CLAUDE.md import, skills, MCP config
a4 doctor --json    # exit 0 = ready; each check carries a fix
a4 explore --json   # live data, no account needed

Building from source

Only for unreleased builds. A Cargo-built binary is not managed by the installer: a4 self update refuses it and tells you to run cargo install a4-cli --force instead.

cargo install a4-cli

---

Global Options

Option	Description
--config, -c <path>	Path to arete.toml (default: arete.toml)
--json	Output as JSON on stdout; logs go to stderr. Every object has schemaVersion
--yes, -y	Accept defaults; never prompt
--non-interactive	Never prompt; a missing required input is an error naming the flag to pass
--verbose	Enable verbose output
--api-url <url>	Override the API endpoint
--help, -h	Show help
--version, -V	Show version
--completions <SHELL>	Generate shell completions (bash, zsh, fish, powershell, elvish)

Prompts are also disabled when A4_NON_INTERACTIVE=1 or CI is set, or when stdin is not a terminal. No command ever waits on stdin in those cases.

Exit codes: 0 success (including warnings), 1 command failure, 2 usage error, 10 update available (a4 self update --check only).

---

Quick Reference

Command	Description
a4 create [name]	Scaffold a new app from a template
a4 init	Set up the project for Arete and coding agents
a4 doctor	Check install, project, auth, agents
a4 self install	Finish installing the a4 binary
a4 self update / a4 upgrade	Update a4 in place
a4 self uninstall	Remove a4
a4 mcp	Run the stream MCP server (stdio)
a4 auth signup	Register an agent account
a4 program build <idl>	Build a portable ProgramSpec
a4 stack compose	Compose ProgramSpecs and aliased LiveSpecs
a4 sdk create --manifest ... --ts	Generate a TypeScript SDK from a StackManifest
a4 sdk create --manifest ... --rust	Generate a Rust SDK from a StackManifest
a4 up <manifest>	Deploy one exact StackManifest
a4 status	Show project overview
a4 stack list	List deployed stacks
a4 telemetry status	Show telemetry status
a4 explore	Discover installable stacks
a4 explore programs	Discover installable standalone programs
a4 explore stack <ref>	Inspect an exact stack install descriptor
a4 explore program <ref>	Inspect an exact program install descriptor
a4 know search --query <intent>	Search the knowledge layer by intent
a4 know protocol <slug>	Curated knowledge for one protocol
a4 know program <slug>	Curated annotations for one program
a4 know recipe <slug>	One cross-protocol recipe
a4 know concepts	Concept and category vocabularies

One binary

Every install route (install.sh, install.ps1, npx @usearete/a4 install) puts the same prebuilt binary at ~/.local/bin/a4. npx @usearete/a4 <command> runs that binary too, installing it first if needed.

---

Create a New App

a4 create [name]

Scaffold a new Arete project from a template. This is the fastest way to get started.

# Interactive — prompts for name and template
npx @usearete/a4 create

# With project name
npx @usearete/a4 create my-app

# With specific template
npx @usearete/a4 create my-app --template react-ore

Available templates:

Template	Aliases	Description
react-ore	ore-react	ORE mining rounds viewer (React + Vite)
rust-ore	ore-rust	ORE mining rounds client (Rust + Tokio)
typescript-ore	ore-typescript, ts-ore, ore-ts	ORE mining rounds client (TypeScript CLI)

Options:

Flag	Description
--template <name>	Skip interactive selection
--offline	Use cached templates only
--force-refresh	Clear template cache and re-download
--skip-install	Don’t run npm install automatically

Templates are downloaded from GitHub releases and cached in ~/.arete/templates/.

---

Project Setup

a4 init

Set up the current directory for Arete and for the coding agents that work in it.

a4 init -y                       # all detected agents, project scope
a4 init -y --json                # machine-readable report
a4 init -y --dry-run             # report what would change, write nothing
a4 init -y --global              # skills and MCP config for your user, not the project
a4 init -y --agents cursor,codex # explicit agent list (also: all | none)
a4 init -y --no-skills --no-mcp  # manifest and AGENTS.md only

What it writes (every item is an upsert and reports created | updated | unchanged | skipped(reason)):

Item	Path	Notes
Manifest	arete.toml	Created if absent; left untouched if present unless --force, which rewrites only [project]. Name from --name or the directory basename
Agent guidance	AGENTS.md	A managed block between <!-- BEGIN:arete v2 --> and <!-- END:arete -->; content outside the markers is never touched
Claude Code bridge	CLAUDE.md	Created as @AGENTS.md, or that line is inserted first if the file exists
Gemini context	.gemini/settings.json	context.fileName gains AGENTS.md (Gemini CLI only)
Skills	per agent, e.g. .claude/skills/, .agents/skills/	Runs npx -y skills add AreteA4/skills --skill '*' --agent <ids> -y. skipped(npx not found) without Node; the fix is printed
MCP config	per agent (table below)	Two servers: arete (stdio, a4 mcp) and arete-docs (https://docs.arete.run/mcp). Only these two keys are set; the rest of the file is preserved

Options:

Flag	Description
-y, --non-interactive	Never prompt
--json	JSON report (below)
--dry-run	Same report with dryRun: true and would-* statuses; writes nothing
--force	Rewrite the [project] block of an existing arete.toml
--name <project>	Project name (default: directory basename)
--agents <list|all|none>	Agents to configure (default: detected)
--global	Install skills and MCP config for your user instead of the project
--no-manifest, --no-agents-md, --no-skills, --no-mcp	Skip a writer
--skills-ref <git ref>	Skills version to install (default main)

Agent detection. Project signals win over home-directory signals. If nothing is detected and --agents is absent, init still writes the agent-independent set (arete.toml, AGENTS.md, CLAUDE.md, .agents/skills, .mcp.json) and adds a warning; it does not fail.

Agent	Project signal	MCP file (project / --global)
claude-code	.claude/, CLAUDE.md, .mcp.json, CLAUDECODE=1	.mcp.json / ~/.claude.json
cursor	.cursor/	.cursor/mcp.json / ~/.cursor/mcp.json
vscode	.vscode/	.vscode/mcp.json / —
copilot-cli	.github/copilot-instructions.md	.mcp.json / ~/.copilot/mcp-config.json
codex	.codex/	.codex/config.toml / ~/.codex/config.toml
opencode	opencode.json, opencode.jsonc, .opencode/	opencode.json / ~/.config/opencode/opencode.json
gemini-cli	.gemini/	.gemini/settings.json / ~/.gemini/settings.json
windsurf	.windsurf/	— / ~/.codeium/windsurf/mcp_config.json
cline	.clinerules/	— / ~/.cline/mcp.json
zed	.zed/	.zed/settings.json / ~/.config/zed/settings.json
amp	.amp/	.amp/settings.json / ~/.config/amp/settings.json
kiro	.kiro/	.kiro/settings/mcp.json / ~/.kiro/settings/mcp.json
roo	.roo/	.roo/mcp.json / —
goose	.goose/	.goose/config.yaml / ~/.config/goose/config.yaml

Per-host MCP shapes are listed on the MCP Server page. The command is the absolute path from the install receipt when one exists, so GUI hosts that do not inherit your shell PATH still find it.

--json output:

{
  "schemaVersion": 1,
  "dryRun": false,
  "detectedAgents": [{ "id": "claude-code", "how": "env" }, { "id": "cursor", "how": "home" }],
  "selectedAgents": ["claude-code", "cursor"],
  "results": [
    { "item": "arete.toml", "status": "created", "path": "arete.toml" },
    { "item": "agents-md", "status": "updated", "path": "AGENTS.md" },
    { "item": "claude-md", "status": "unchanged", "path": "CLAUDE.md" },
    { "item": "skills", "status": "skipped", "reason": "npx not found", "fix": "npx skills add AreteA4/skills" },
    { "item": "mcp:claude-code", "status": "created", "path": ".mcp.json" },
    { "item": "mcp:cursor", "status": "created", "path": ".cursor/mcp.json" }
  ],
  "warnings": [],
  "next": ["a4 doctor --json", "a4 explore --json"]
}

init is idempotent: running it again changes no file and reports every item as unchanged. Exit 1 only if a writer errored ("status": "error").

a4 doctor

Read-only check of everything init writes plus the environment.

a4 doctor
a4 doctor --json
a4 doctor --fix      # re-run the init writers for every agents.* warning, then re-check

Check id	What it verifies	On failure
cli.version	Install receipt present; current version vs latest (2 s timeout)	warn: a4 self update (info when offline)
cli.install	Receipt binary is the running executable; no a4 shadowing it on PATH	warn with the shadowing path
cli.path	Install directory is on PATH	warn: prints the export PATH=… line
project.manifest	arete.toml parses	fail: a4 init / a4 config validate
project.lock	arete.lock is fresh	warn: a4 install
auth.credentials	Key present for the active API URL	info: a4 auth signup (not needed to explore)
auth.whoami	Credentials are accepted by the server	fail: a4 auth login --key …
net.api	https://api.arete.run reachable	fail
net.docs-mcp	https://docs.arete.run/mcp reachable	warn
tools.node	npx on PATH (skills only)	info
tools.rust	cargo on PATH (authoring only)	info; warn if arete.toml has [authoring]
agents.detected	Detected agents	info
agents.<id>.mcp	Both MCP servers present with the expected shape	warn: a4 doctor --fix
agents.<id>.skills	All five Arete workflow skills installed for that agent	warn: npx skills add AreteA4/skills --agent <id>
agents.agents-md	AGENTS.md block present and current (v2)	warn: a4 doctor --fix
agents.claude-md	CLAUDE.md imports @AGENTS.md (Claude Code only)	warn
agents.gemini-context	Gemini context.fileName includes AGENTS.md (Gemini CLI only)	warn
agents.codex-trust	Project trusted in ~/.codex/config.toml (Codex only)	info

--json output:

{
  "schemaVersion": 1,
  "status": "ok",
  "checks": [{ "id": "cli.version", "status": "ok", "detail": "0.13.0 (latest)", "fix": null }]
}

status is ok, warn, or fail; each check is ok | warn | fail | info. Exit 0 for ok and warn, 1 for fail. --fix never touches auth, network, or tool checks. Human output is one line per check followed by the list of fixes.

a4 config validate

Validate your configuration.

a4 config validate

---

Managing the Binary

a4 self install

Finish installing the binary that is currently running. The bootstrappers (install.sh, install.ps1, npx @usearete/a4 install) call this for you; run it yourself only for a manually downloaded release asset.

a4 self install [--install-dir <DIR>] [--no-modify-path] [--source <sh|ps1|npm|manual>]
                [--checksums <FILE> --signature <FILE>] [--force] [--json]

Flag	Description
--install-dir <DIR>	Target directory (else A4_INSTALL_DIR, XDG_BIN_HOME, ~/.local/bin)
--no-modify-path	Skip shell-profile / Windows PATH edits (also A4_NO_MODIFY_PATH=1 or CI)
--checksums <FILE> --signature <FILE>	Verify the minisign signature over checksums.txt and the binary’s SHA-256 before installing; omitted for manual installs ("verified": false in the receipt)
--source <name>	Recorded in the receipt
--force	Copy even when the target is already this binary (a re-run normally skips the copy)

Writes ~/.arete/receipt.json (version, binary, installDir, platform, source, verified, modifyPath, installedAt), adds ~/.local/bin to ~/.profile and your shell’s rc file (or HKCU\Environment\Path on Windows, and $GITHUB_PATH in Actions) when it is not already there, and always ends stdout with the A4_BIN= and export PATH= lines. With --json the receipt plus pathModified and shadowedBy precede them.

a4 self update

Replace the installed binary with a newer (or an explicitly chosen) release. a4 upgrade is an alias with identical arguments.

a4 self update                    # latest
a4 self update 0.14.0             # specific version (downgrades allowed when explicit)
a4 self update --check            # exit 10 if an update is available, 0 if current
a4 self update --check --json     # {"current","latest","updateAvailable"}
a4 self update --dry-run          # download and verify, print the plan, change nothing

The download is verified (SHA-256 and the minisign signature; mandatory here) before the binary at the receipt path is swapped in place and the receipt updated. Requires the install receipt: a Cargo-built a4 gets a4 was not installed by the Arete installer and must be rebuilt with cargo install a4-cli --force.

Once a day, when stderr is a terminal, a4 prints a4 0.14.0 is available (you have 0.13.0). Run: a4 self update after a command. Set A4_NO_UPDATE_CHECK=1 to disable this notice; it is never shown under CI, with --json, or for self, upgrade, mcp, and stream. There is no background auto-update.

a4 self uninstall

a4 self uninstall [--json]

Removes the binary, the receipt, and the PATH lines self install added. Leaves ~/.arete/credentials.toml and prints what it left behind.

---

MCP Server

a4 mcp

Run the Arete stream MCP server over stdio (registry discovery, knowledge layer, live entity reads). Nothing but MCP frames is written to stdout; logs go to stderr.

a4 mcp

a4 init writes the config for every detected agent. The Claude Code shape (.mcp.json):

{
  "mcpServers": {
    "arete": { "type": "stdio", "command": "a4", "args": ["mcp"] },
    "arete-docs": { "type": "http", "url": "https://docs.arete.run/mcp" }
  }
}

Credentials resolve from ARETE_API_KEY, then ~/.arete/credentials.toml. The npm package @usearete/mcp is deprecated in favour of this command. Tools and per-host shapes: MCP Server.

a4 config validate

Validate your configuration.

a4 config validate

---

Authentication

Exploring and installing public SDKs needs no account. Deploying and the knowledge layer do. Agents register themselves with a4 auth signup; humans get keys from arete.run/keys and use a4 auth login --key.

a4 auth signup

Register a new agent account and store its key.

a4 auth signup                 # server picks a display name
a4 auth signup my-agent        # explicit display name
a4 auth signup --json
a4 auth signup --force         # replace credentials that already exist for this API URL

Calls POST /api/agents/signup, saves the key to ~/.arete/credentials.toml, and prints the agent slug and the credentials path. The key itself is never printed in human mode.

Options:

Flag	Description
[name]	Display name (optional)
--force	Overwrite existing credentials for this API URL; otherwise the command refuses and points at a4 auth status

--json output:

{ "schemaVersion": 1, "slug": "agt_7k2m9q1r", "displayName": "my-agent", "credentialsPath": "/home/x/.arete/credentials.toml", "apiKey": "a4_ak_…" }

apiKey is a secret. It is included so an agent can pass it as ARETE_API_KEY to a sub-process; do not log it or commit it.

Rate limit: 5 signups per hour per IP. On 429 the command prints Signup limit reached (5 per hour per IP). Retry later, or use a key from https://arete.run/keys: a4 auth login --key <a4_ak_…>.

a4 auth login

Save a human-issued API key.

# Prompts for the key only in an interactive terminal
a4 auth login

# Pass directly (required when non-interactive)
a4 auth login --key <a4_ak_...>

Options:

Flag	Description
--key, -k	API key. When omitted in a non-interactive run the error lists this flag and a4 auth signup

a4 auth logout

Remove stored credentials.

a4 auth logout

a4 auth status

Check local authentication status.

a4 auth status

a4 auth whoami

Verify authentication with server.

a4 auth whoami

Credentials location: ~/.arete/credentials.toml

---

Schema Discovery

a4 explore

Discover installable resources through the same deployment-pinned descriptors used by a4 install. Public resources work without authentication; logging in also exposes global resources.

# List all available stacks
a4 explore

# Show exact StackManifest, AST, LiveSpec, view, and Program Release identities
a4 explore stack ore

# List and inspect standalone programs
a4 explore programs
a4 explore program spl-token

# Legacy stack and entity forms remain supported
a4 explore ore
a4 explore ore OreRound

# JSON output (for agents and scripts)
a4 explore --json
a4 explore programs --json
a4 explore stack ore --json
a4 explore program spl-token --json
a4 explore ore OreRound --json

Arguments:

Argument	Description
<stack-ref>	Hosted stack deployment/install reference
<program-ref>	Program install name or program ID
[entity]	Optional exact-LiveSpec entity drill-down (alias:entity resolves ambiguity)

Output varies by specificity:

Command	Shows
a4 explore	Available stacks
a4 explore programs	Complete promoted Program Release + Program Read installations
a4 explore stack <ref>	Exact identities, aliases, selected views, programs, auth, SDK targets, and install command
a4 explore program <ref>	Program identity, accounts, instructions, events, types, Program Read, and install command
a4 explore <stack> [entity]	Legacy syntax routed through descriptor-backed stack exploration

Every JSON response includes schemaVersion. Exploration never selects a latest AST independently and never falls back when an install descriptor is incomplete. For an owned stack diagnostic, use a4 stack show <ref>.

a4 know

Query the curated knowledge layer: which protocols, programs, stacks, and recipes serve an intent, and what the platform can do for each (read account state, build transactions, subscribe to a hosted stack). Every subcommand requires an API key saved by a4 auth login and accepts --json, which prints the API response verbatim.

# Search by intent; results carry read / build / subscribe coverage flags
a4 know search --query "monitor swaps"
a4 know search --concept swap --category dex --limit 10

# One protocol: programs with roles, related protocols, live stacks, coverage
a4 know protocol meteora-damm

# One program's annotations, one section at a time
a4 know program meteora-cp-amm                          # summary (default)
a4 know program meteora-cp-amm --section instructions
a4 know program meteora-cp-amm --section accounts
a4 know program meteora-cp-amm --section surface        # typed SDK operations with bindings

# One cross-protocol recipe
a4 know recipe execute-presale-purchase-via-squads

# Concept and category slugs for --concept / --category
a4 know concepts

search options:

Flag	Description
--query, -q <text>	Free-text intent; matches concept names and synonyms first
--concept <slug>	Filter by concept slug (see a4 know concepts)
--category <slug>	Filter by category slug (see a4 know concepts)
--limit <n>	Maximum number of results

At least one of --query, --concept, or --category is required.

program options:

Flag	Description
--section <name>	summary (default), instructions, accounts, or surface

Slugs are bare identifiers (meteora-damm), not URLs or paths; unknown slugs return a not-found error. The catalog is growing, so a protocol with no entry is not evidence that it is unsupported — fall back to a4 explore and a4 idl.

---

Deployment

a4 up <manifest>

Deploy the exact composition described by a local StackManifest. The control plane resolves every ProgramSpec to an immutable hosted Program Release, prepares each aliased LiveSpec independently, then returns deployment and endpoint bindings. Those operational bindings are not part of the portable StackManifest hash.

# Deploy an exact manifest
a4 up .arete/MyStack.stack-manifest.json

# Deploy to branch
a4 up .arete/MyStack.stack-manifest.json --branch staging

# Preview deployment
a4 up .arete/MyStack.stack-manifest.json --preview

# Preview what would be deployed (no actual deployment)
a4 up .arete/MyStack.stack-manifest.json --dry-run

Options:

Flag	Description
--branch, -b <name>	Deploy to named branch
--preview	Create preview deployment
--dry-run	Show what would be deployed without deploying

a4 status

Show overview of all stacks, builds, and deployments.

a4 status
a4 status --json

---

Stack Management

a4 program build <idl>

Normalize an IDL into a portable, endpoint-free ProgramSpec:

a4 program build ./idl/my-program.json \
  --output ./.arete/my-program.program-spec.json

# Supply the program ID when the IDL omits it
a4 program build ./idl/my-program.json \
  --program-id <program-id> \
  --output ./.arete/my-program.program-spec.json

The output describes public program behavior. It does not select a hosted decoder release or Program Read endpoint.

a4 stack compose

Compose portable ProgramSpec and aliased LiveSpec artifacts into a StackManifest.

a4 stack compose --name jurassic \
  --program ./programs/spl-token.program-spec.json \
  --live squads=./squads.live-spec.json \
  --live presale=./presale.live-spec.json \
  --artifact-dir ./.arete \
  --selected-view squads=Multisig/state \
  --selected-view presale=Presale/list \
  --output ./Jurassic.stack-manifest.json

Repeat --program, --live, and --artifact-dir as needed. Each --live requires a stable alias=path pair, so multiple LiveSpecs can expose the same entity or program names without losing ownership. When --selected-view is omitted, all views from every supplied LiveSpec are selected. When present, its alias=view_id values form the exact allowlist in command-line order.

A StackManifest composes portable identities only. It contains no WebSocket, Program Read, chain, or transaction endpoint and does not require those transports to be co-located.

a4 stack list

List all stacks with their deployment status.

a4 stack list
a4 stack list --json

Output:

STACK              STATUS     VERSION  URL
settlement-game    active     v3       wss://settlement-game.stack.arete.run
token-tracker      active     v1       wss://token-tracker.stack.arete.run

a4 stack show <stack-name>

Show detailed stack information including deployment status and versions.

a4 stack show my-stack
a4 stack show my-stack --version 3
a4 stack show my-stack -v 3

Options:

Flag	Description
--version, -v <n>	Show specific version details

Output includes:

• Entity information
• Deployment status and URL
• Latest version details
• Recent builds

a4 stack versions <stack-name>

Show version history.

a4 stack versions my-stack
a4 stack versions my-stack --limit 10
a4 stack versions my-stack -l 10

Options:

Flag	Description
--limit, -l <n>	Maximum number of versions (default: 20)

a4 stack delete <stack-name>

Delete a stack from remote.

a4 stack delete my-stack
a4 stack delete my-stack --force  # Skip confirmation
a4 stack delete my-stack -f

Options:

Flag	Description
--force, -f	Skip confirmation prompt

a4 stack stop <stack-name>

Stop a deployment.

a4 stack stop my-stack
a4 stack stop my-stack --branch staging
a4 stack stop my-stack --force  # Skip confirmation

Options:

Flag	Description
--branch <name>	Branch deployment to stop
--force, -f	Skip confirmation prompt

---

SDK Dependencies

a4 install
a4 install --locked
a4 install --dry-run
a4 install stack ore@^1.4.0 --ts
a4 install program spl-token@=4.0.2 --rust
a4 update
a4 update stack ore
a4 remove program spl-token
a4 remove stack ore --keep-output

With no package argument, a4 install resolves the complete strict arete.toml graph and atomically commits generated outputs plus arete.lock. A package add saves dependency intent before resolving the whole project. Use --no-save for one-off exact registry generation.

a4 remove <stack|program> <alias> removes the dependency from the manifest, prunes its lock entry, and deletes only generated output whose provenance matches that project dependency. It refuses output containing unowned files; --keep-output removes only the manifest and lock entries.

a4 sdk list reports normalized manifest dependencies and lock status. Low-level a4 sdk create accepts explicit --manifest or --program-spec artifact inputs and hosted exact descriptors. It is a compatibility/direct-descriptor tool: it never writes arete.toml or arete.lock, and a4 install never falls back to it.

Private programs and stacks

Owner-private programs (a4 program push) and private production stacks (a4 up) publish immutable, owner-scoped registry packages as part of the same lifecycle step that makes them ready or active, so they install through the ordinary dependency workflow:

a4 auth login                                   # private packages require the owner's session
a4 install program My-Program --rust            # by alias (case-insensitive)
a4 install program upr_AbC123... --ts           # by stable reference
a4 install stack my-stack-a1b2 --python         # by deployed atom name
a4 install                                      # reinstall: exact lock, never floats
a4 update program my-program                    # explicit update to the newest revision

Four things are kept distinct:

Concept	Where it lives	Rule
Remote lookup	source = { registry = "My-Program" }	Sent to the registry unchanged; an alias, a stable upr_... reference, or a deployed stack name.
Local alias	the [dependencies.<kind>.<alias>] key and generated module/crate/package names	Derived deterministically from the lookup (lower-case, - separators, pkg- before a leading digit, -pkg after a reserved word) or set with --alias; must be a valid identifier in Rust, TypeScript, and Python. Regeneration on another machine yields the same names.
Version requirement	version = "^0.1.0"	Private revisions are platform-managed (0.1.0, then the next patch); the requirement is what a4 update may advance within.
Exact lock	arete.lock package_release_hash	Immutable release identity; reinstall resolves exactly this, a4 update replaces it only after generation succeeds.

Public catalog packages win name resolution; the authenticated owner’s private package is consulted next. Another account, an anonymous client, or an unknown name all receive the same not-found response, and the CLI never retries a failed manifest lookup against a differently scoped endpoint. Optional server SDK extensions are optional: without them the core client is generated.

Chain reads and transaction submission for hosted programs and stacks use the managed Solana gateway descriptor embedded in the generated SDK, not the tenant stream URL; a stack descriptor reporting transactions: false describes the tenant runtime endpoint, not the account’s entitlement.

Configuration File

manifest_version = 1

[project]
name = "my-project"
private = true

[sdk]
targets = ["typescript", "rust"]

[sdk.typescript]
output_dir = "./src/generated"
package = "@my-org/arete-generated"

[dependencies.stacks.ore]
source = { registry = "ore" }
version = "^1.4.0"

[authoring.stacks.local]
manifest = "./.arete/MyStack.stack-manifest.json"
artifact_roots = ["./.arete"]

Default output paths are kind-scoped. TypeScript uses <output_dir>/stacks/<alias> or <output_dir>/programs/<alias>. Rust and Python use those same kind directories with an <alias>-stack or <alias>-program leaf (plus any configured prefix). Stack and program aliases may match; explicit per-dependency outputs are used exactly as written.

Run a4 config validate for offline strict-schema, local artifact closure, output collision, path-policy, and lock-freshness checks.

Build Process

Status Flow

pending → uploading → queued → building → pushing → deploying → completed
                                                              ↘ failed

Build Phases

Phase	Description
SUBMITTED	Queued for processing
PROVISIONING	Starting build environment
DOWNLOAD_SOURCE	Preparing source
INSTALL	Installing dependencies
PRE_BUILD	Preparing build
BUILD	Compiling
POST_BUILD	Finalizing
UPLOAD_ARTIFACTS	Publishing image
FINALIZING	Deploying to runtime

---

Typical Workflows

First-Time Setup

# Install the CLI (macOS / Linux; Windows: irm https://arete.run/install.ps1 | iex)
curl -fsSL https://arete.run/install.sh | sh

# Set up the project: manifest, AGENTS.md, skills, MCP config
a4 init -y

# Verify
a4 doctor --json

# Discover live data (no account needed)
a4 explore --json

# Only when deploying or using the knowledge layer
a4 auth signup                     # agent
a4 auth login --key <a4_ak_...>    # human-issued key

Development Cycle

# Make changes to stack, rebuild Rust crate
cargo build

# Deploy the generated manifest
a4 up .arete/MyStack.stack-manifest.json

# Check status
a4 status

Branch Deploys

# Deploy feature branch
a4 up .arete/MyStack.stack-manifest.json --branch feature-x

# Check deployment
a4 stack list

# Clean up when done
a4 stack stop my-stack --branch feature-x

Telemetry

Arete collects anonymous usage data to improve the CLI. No personal information or project details are sent.

a4 telemetry status

Show current telemetry status.

a4 telemetry status

a4 telemetry enable

Enable telemetry collection.

a4 telemetry enable

a4 telemetry disable

Disable telemetry collection.

a4 telemetry disable

---

Environment Variables

Variable	Description
ARETE_API_URL	Override API endpoint
ARETE_API_KEY	API key; takes precedence over the credentials file
ARETE_CREDENTIALS_PATH	Override the credentials file
A4_INSTALL_DIR	Install directory for a4 self install and the bootstrappers
A4_NO_MODIFY_PATH=1	Do not edit shell profiles or the Windows PATH on install
A4_NO_UPDATE_CHECK=1	Disable the once-per-day “update available” notice
A4_NON_INTERACTIVE=1	Never prompt (same as --non-interactive)
A4_VERSION	Version for install.sh / install.ps1 to install
CI	When set: never prompt, no PATH edits, no update notice, no telemetry banner
DO_NOT_TRACK=1	Disable telemetry (standard)
ARETE_TELEMETRY_DISABLED=1	Disable telemetry (Arete-specific)

---

Error Reference

Error	Solution
Not authenticated	Run a4 auth signup (or a4 auth login --key <a4_ak_…>)
a4: command not found	Run export PATH="$HOME/.local/bin:$PATH" or use the A4_BIN= path the installer printed; a4 doctor reports this as cli.path
a4 was not installed by the Arete installer	Reinstall with curl -fsSL https://arete.run/install.sh | sh; Cargo builds must use cargo install a4-cli --force
Stack not found	Check a4 stack list for available stacks
Stack file not found	Run cargo build to generate stack spec
Build failed	Try again
Config invalid	Run a4 config validate

---

Endpoint and DNS Handoff

After deployment, inspect the returned binding or use a4 stack show to obtain the assigned endpoints. Live WebSocket/query, Program Read, chain-read, and transaction endpoints are separate bindings and must not be derived from one another.

a4 stack show <deployed-stack-name>

Arete does not require a particular DNS provider. If a deployment should use a custom hostname, the operator configures the record, certificate, and any CDN or proxy policy with the provider of their choice after receiving the binding.