a4-cli

Command-line tool for building, deploying, and managing Arete stream stacks.

Installation

cargo install a4-cli

From Source

git clone https://github.com/AreteA4/arete.git
cd arete
cargo install --path cli

Quick Start

# Initialize project
a4 init

# Authenticate
a4 auth login

# Build explicit artifacts and deploy the exact manifest
cargo build
a4 up .arete/MyStack.stack-manifest.json

The deployment returns operational bindings for the exact StackManifest.

Command Overview

Daily Workflow

# Make changes to your stack, rebuild
cargo build

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

# Check status
a4 status

Stack Commands

a4 stack list

List all stacks with deployment status:

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

Show detailed information:

a4 stack show settlement-game

Shows: entity info, deployment status, version history, recent builds.

a4 stack push [name] (legacy)

Push a legacy configured composite input. This compatibility path is retained only through August 31, 2026:

a4 stack push                  # Push all
a4 stack push settlement-game  # Push one

a4 stack versions <name>

Show version history:

a4 stack versions settlement-game --limit 10

a4 stack rollback <name>

Rollback to a previous version:

a4 stack rollback settlement-game          # Previous version
a4 stack rollback settlement-game --to 2   # Specific version

a4 stack delete <name>

Delete a stack:

a4 stack delete settlement-game

Deployment

a4 up <manifest>

Deploy one exact local StackManifest:

a4 up .arete/MyStack.stack-manifest.json
a4 up .arete/MyStack.stack-manifest.json --branch staging
a4 up .arete/MyStack.stack-manifest.json --preview

Composite .stack.json is an input-only compatibility adapter through August 31, 2026. New deployments use the manifest path.

Authentication

a4 auth login       # Login
a4 auth logout      # Logout
a4 auth whoami      # Verify with server

Credentials: ~/.arete/credentials.toml

Registry Exploration

Exploration uses the same deployment-pinned install descriptors as a4 install, so the reported StackManifest, LiveSpec, AST, and Program Release identities are the ones an installation will consume.

a4 explore                              # List stacks
a4 explore programs                     # List complete installable programs
a4 explore stack ore --json             # Exact stack descriptor summary
a4 explore program spl-token --json     # Accounts, instructions, and release

Legacy stack forms remain valid:

a4 explore ore
a4 explore ore OreRound

Every JSON explore response includes schemaVersion. Stack exploration shows LiveSpec aliases without flattening multi-live compositions and includes only the views selected by the exact StackManifest. If descriptor assembly fails, the command reports the deployment/publication problem instead of falling back to a different AST.

SDK Generation

a4 install ore-stack-abc123 --ts              # Install a published hosted stack SDK
a4 install ore-stack-abc123 --rust            # Install a published hosted Rust stack SDK
a4 install program spl-token --ts             # Install a published hosted program SDK
a4 sdk list                                   # List available stacks
a4 sdk create --manifest .arete/MyStack.stack-manifest.json --ts
a4 sdk create --manifest .arete/MyStack.stack-manifest.json --rust
a4 sdk create --program-spec .arete/token.program-spec.json --program-only --ts

SDK generation writes local source and does not publish a package.

Configuration

File: arete.toml

[project]
name = "my-project"

[sdk]
output_dir = "./generated"

# Legacy composite inputs (compatibility only through August 31, 2026)
[[stacks]]
name = "my-game"
stack = ".arete/SettlementGame.stack.json"

For most projects, you only need:

[project]
name = "my-project"

New SDK and deployment workflows pass an explicit StackManifest path.

Endpoint and DNS Handoff

Live, Program Read, chain, and transaction endpoints are independent bindings. Operators map them through their chosen DNS/CDN provider and publish generated SDK packages manually. Hosted TypeScript composition output preserves the full Solana gateway descriptors and exports a create<StackName>HostedSession helper. That helper creates authenticated chain and transaction transports from the generated bindings; the generic composition helper still requires explicit transports.

Environment Variables

Troubleshooting

License

Apache-2.0