--- title: "CLI Command Reference" editUrl: true head: [] template: "doc" sidebar: {"order":1,"hidden":false,"attrs":{}} pagefind: true draft: false --- Complete reference for the Arete CLI (`a4`). --- ## Global Options | Option | Description | | ----------------------- | ---------------------------------------------------------------- | | `--config, -c ` | Path to arete.toml (default: `arete.toml`) | | `--json` | Output as JSON | | `--verbose` | Enable verbose output | | `--help, -h` | Show help | | `--version, -V` | Show version | | `--completions ` | 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 | :::note[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. ```bash # 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 ` | 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. ```bash a4 init ``` Creates `arete.toml` with auto-discovered stacks from `.arete/*.stack.json`. ### a4 config validate Validate your configuration. ```bash 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. ```bash # Interactive — prompts for API key a4 auth login # Or pass directly a4 auth login --key ``` **Options:** | Flag | Description | | ----------- | --------------------------------- | | `--key, -k` | API key (prompts if not provided) | ### a4 auth logout Remove stored credentials. ```bash a4 auth logout ``` ### a4 auth status Check local authentication status. ```bash a4 auth status ``` ### a4 auth whoami Verify authentication with server. ```bash 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. ```bash # 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 entities, views, and field counts | | `a4 explore ` | 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. ```bash # 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 ` | 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. ```bash a4 status a4 status --json ``` --- ## Stack Management ### a4 stack list List all stacks with their deployment status. ```bash 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. ```bash # Push all stacks a4 stack push # Push specific stack a4 stack push my-stack ``` ### a4 stack show \ Show detailed stack information including deployment status and versions. ```bash a4 stack show my-stack a4 stack show my-stack --version 3 a4 stack show my-stack -v 3 ``` **Options:** | Flag | Description | | ------------------- | ----------------------------- | | `--version, -v ` | Show specific version details | **Output includes:** - Entity information - Deployment status and URL - Latest version details - Recent builds ### a4 stack versions \ Show version history. ```bash a4 stack versions my-stack a4 stack versions my-stack --limit 10 a4 stack versions my-stack -l 10 ``` **Options:** | Flag | Description | | ----------------- | ---------------------------------------- | | `--limit, -l ` | Maximum number of versions (default: 20) | ### a4 stack delete \ Delete a stack from remote. ```bash 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 \ Rollback to a previous deployment. ```bash # 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 ` | Target version | | `--build ` | Target build ID | | `--branch ` | Branch to rollback (default: production) | | `--rebuild` | Force full rebuild | | `--no-wait` | Don't watch progress | ### a4 stack stop \ Stop a deployment. ```bash a4 stack stop my-stack a4 stack stop my-stack --branch staging a4 stack stop my-stack --force # Skip confirmation ``` **Options:** | Flag | Description | | ----------------- | ------------------------- | | `--branch ` | Branch deployment to stop | | `--force, -f` | Skip confirmation prompt | --- ## SDK Generation ### a4 sdk list List stacks available for SDK generation. ```bash a4 sdk list ``` ### a4 sdk create typescript \ Generate TypeScript SDK. ```bash 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 ` | Output file path (overrides config) | | `--package-name, -p ` | Package name for TypeScript | | `--url ` | WebSocket URL for the stack | ### a4 sdk create rust \ Generate Rust SDK crate. ```bash 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 ` | Output directory path (overrides config) | | `--crate-name ` | Custom crate name for generated Rust crate | | `--module` | Generate as a module (mod.rs) instead of a standalone crate | | `--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` ```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: ```toml [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 ```bash # Initialize project a4 init # Login with your API key a4 auth login # Validate configuration a4 config validate ``` ### Development Cycle ```bash # Make changes to stack, rebuild Rust crate cargo build # Deploy a4 up my-stack # Check status a4 status ``` ### Branch Deploys ```bash # 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 ```bash # 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. ```bash a4 telemetry status ``` ### a4 telemetry enable Enable telemetry collection. ```bash a4 telemetry enable ``` ### a4 telemetry disable Disable telemetry collection. ```bash 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: ```bash a4 stack show ```