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).

---

Global Options

Option	Description
--config, -c <path>	Path to arete.toml (default: arete.toml)
--json	Output as JSON
--verbose	Enable verbose output
--help, -h	Show help
--version, -V	Show version
--completions <SHELL>	Generate shell completions (bash, zsh, fish, powershell, elvish)

---

Quick Reference

Command	Description
a4 create [name]	Scaffold a new app from a template
a4 init	Initialize a stack project
a4 up [stack]	Deploy stack (push + build + deploy)
a4 push [stack]	Push stack to remote (alias)
a4 status	Show project overview
a4 stack list	List all stacks
a4 stack show	Show stack details
a4 telemetry status	Show telemetry status
a4 explore	Discover stacks and schemas

npm vs Cargo

When installed via npm (npm install -g @usearete/a4), the command is a4. When installed via Cargo (cargo install a4-cli), the command is also a4. Both are the same CLI.

---

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

Initialize a new Arete project.

a4 init

Creates arete.toml with auto-discovered stacks from .arete/*.stack.json.

a4 config validate

Validate your configuration.

a4 config validate

---

Authentication

Arete is currently in closed beta. Contact us to receive an API key.

a4 auth login

Save your API key to authenticate.

# Interactive — prompts for API key
a4 auth login

# Or pass directly
a4 auth login --key <your-api-key>

Options:

Flag	Description
--key, -k	API key (prompts if not provided)

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 available stacks and explore their schemas. Works without authentication for public stacks.

# List all available stacks
a4 explore

# Show entities and views for a stack
a4 explore ore

# Show fields and types for a specific entity
a4 explore ore OreRound

# JSON output (for agents and scripts)
a4 explore --json
a4 explore ore --json
a4 explore ore OreRound --json

Arguments:

Argument	Description
[name]	Stack name to explore
[entity]	Entity name to show field details

Output varies by specificity:

Command	Shows
a4 explore	All available stacks with entity names
a4 explore <stack>	Stack entities, views, and field counts
a4 explore <stack> <entity>	Entity fields with types, sections, and views

Public stacks are visible without authentication. Log in with a4 auth login to also see global stacks and your own deployed stacks.

---

Deployment

a4 up [stack-name]

Deploy a stack: push, build, and deploy in one command.

# Deploy all stacks
a4 up

# Deploy specific stack
a4 up my-stack

# Deploy to branch
a4 up my-stack --branch staging
# Creates: my-stack-staging.stack.arete.run

# Preview deployment
a4 up my-stack --preview

# Preview what would be deployed (no actual deployment)
a4 up my-stack --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 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 push [stack-name]

Push local stacks to remote.

# Push all stacks
a4 stack push

# Push specific stack
a4 stack push my-stack

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 rollback <stack-name>

Rollback to a previous deployment.

# Rollback to previous version
a4 stack rollback my-stack

# Rollback to specific version
a4 stack rollback my-stack --to 2

# Rollback to specific build
a4 stack rollback my-stack --build 123

# Rollback branch deployment
a4 stack rollback my-stack --branch staging

Options:

Flag	Description
--to <version>	Target version
--build <id>	Target build ID
--branch <name>	Branch to rollback (default: production)
--rebuild	Force full rebuild
--no-wait	Don’t watch progress

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 Generation

a4 sdk list

List stacks available for SDK generation.

a4 sdk list

a4 sdk create typescript <stack-name>

Generate TypeScript SDK.

a4 sdk create typescript my-stack
a4 sdk create typescript my-stack --output ./src/generated/
a4 sdk create typescript my-stack --package-name @myorg/my-sdk
a4 sdk create typescript my-stack --url wss://my-stack.stack.arete.run

Options:

Flag	Description
--output, -o <path>	Output file path (overrides config)
--package-name, -p <name>	Package name for TypeScript
--url <url>	WebSocket URL for the stack

a4 sdk create rust <stack-name>

Generate Rust SDK crate.

a4 sdk create rust my-stack
a4 sdk create rust my-stack --output ./crates/
a4 sdk create rust my-stack --crate-name my-stack-sdk
a4 sdk create rust my-stack --module  # Generate as module instead of crate
a4 sdk create rust my-stack --url wss://my-stack.stack.arete.run

Options:

Flag	Description
--output, -o <path>	Output directory path (overrides config)
--crate-name <name>	Custom crate name for generated Rust crate
--module	Generate as a module (mod.rs) instead of a standalone crate
--url <url>	WebSocket URL for the stack

The --module flag generates the SDK as a Rust module (with mod.rs) that can be embedded directly into an existing crate, rather than creating a standalone crate with its own Cargo.toml. This is useful for monorepo setups or when you want to include generated code within your own crate.

---

Configuration File

File: arete.toml

[project]
name = "my-project"

# SDK generation settings
[sdk]
output_dir = "./generated"                              # Default output for both languages
typescript_output_dir = "./frontend/src/generated"     # Override for TypeScript only
rust_output_dir = "./crates/generated"                 # Override for Rust only
typescript_package = "@myorg/my-sdk"                   # Package name for TypeScript
rust_module_mode = false                               # Generate Rust SDKs as modules by default

# Build preferences
[build]
watch_by_default = true

# Stack definitions
# Auto-discovered from .arete/*.stack.json
# Define explicitly for custom naming or per-stack overrides:
[[stacks]]
name = "my-game"
stack = "SettlementGame"                               # Stack name or path to .stack.json
description = "Settlement game tracking"
typescript_output_file = "./src/generated/game.ts"    # Per-stack TypeScript output path
rust_output_crate = "./crates/game-stack"             # Per-stack Rust output path
rust_module = true                                     # Per-stack: generate as module instead of crate

SDK Configuration Options

Option	Scope	Description
output_dir	[sdk]	Default output directory for both languages
typescript_output_dir	[sdk]	Override output directory for TypeScript SDKs
rust_output_dir	[sdk]	Override output directory for Rust SDKs
typescript_package	[sdk]	Package name for generated TypeScript code
rust_module_mode	[sdk]	Generate Rust SDKs as modules by default
typescript_output_file	[[stacks]]	Per-stack TypeScript output file path
rust_output_crate	[[stacks]]	Per-stack Rust output crate/module directory
rust_module	[[stacks]]	Per-stack override for module vs crate generation

For most projects, you only need:

[project]
name = "my-project"

The CLI auto-discovers stacks from .arete/*.stack.json files.

---

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

# Initialize project
a4 init

# Login with your API key
a4 auth login

# Validate configuration
a4 config validate

Development Cycle

# Make changes to stack, rebuild Rust crate
cargo build

# Deploy
a4 up my-stack

# Check status
a4 status

Branch Deploys

# Deploy feature branch
a4 up my-stack --branch feature-x
# URL: my-stack-feature-x.stack.arete.run

# Check deployment
a4 stack list

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

Rollback

# Quick rollback to previous version
a4 stack rollback my-stack

# Rollback to specific version
a4 stack rollback my-stack --to 2

---

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
DO_NOT_TRACK=1	Disable telemetry (standard)
ARETE_TELEMETRY_DISABLED=1	Disable telemetry (Arete-specific)

---

Error Reference

Error	Solution
Not authenticated	Run a4 auth login
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

---

WebSocket URL Patterns

After successful deployment:

Type	Pattern
Production	wss://{stack-name}.stack.arete.run
Branch	wss://{stack-name}-{branch}.stack.arete.run
Local	ws://localhost:8080

Get the URL with:

a4 stack show <stack-name>