@augustdigital/cli

The august command — a read-only CLI over the August Digital SDK. Inspect vault APY, TVL, positions, redemptions, and user points across EVM, Solana, and Stellar without writing TypeScript.

Read-only by design. There are no signing or write commands.

Install

npm install -g @augustdigital/cli

Or run without installing:

npx -y @augustdigital/cli --help

Quickstart

august init                              # one-time setup
august whoami                            # confirm config + API key status
august vault apy 0xVault --chain 8453    # current APY (human output)
august vault apy eth-coreusdc            # same call, by name
august vault apy 0xVault --chain 8453 --json | jq .data.currentApy

Config layout

august init writes:

~/.augustdigital/
├── config.json    # default chain, RPCs, profile, telemetry
├── keystore.json  # AES-256-GCM; holds your August API key (optional)
├── .session       # mode 0600; decrypted API key + expiry
└── profiles/      # named overlays for chain + RPC sets

Override the root with AUGUST_CONFIG_DIR=….

Auth

If you stored an API key during init, run august login once per shell to unlock the keystore. Subsequent commands read from .session until it expires (default 1h, set config.auth.sessionTtlSec). august logout clears it.

In CI, either set AUGUST_PASSPHRASE (so login runs non-interactively) or skip the keystore entirely and use AUGUST_API_KEY. Env vars always win over the session.

Global flags

Commands

Run august <command> --help for per-command flags and examples.

Vault names

Every command that takes <vault> (and user pnl --vault …) accepts either a raw address or a vault name:

august vault list                           # discover known names per chain
august vault tvl coreusdc                   # bare symbol, chain inferred
august vault tvl eth-coreusdc               # explicit chain prefix
august vault tvl 0xE9B7…32 --chain 1        # raw address (unchanged)

Chain prefixes accepted: eth/mainnet, base, arb/arbitrum, op/optimism, avax/avalanche, bsc/bnb, polygon/matic, hyperevm/hyper, monad, mezo, plasma, ink, flare.

If a bare name matches multiple chains, the CLI returns VAULT_NAME_AMBIGUOUS; either prefix the name or pass --chain. Names come from the upshift metadata endpoint and are cached in-process for 10 minutes — addresses always work without a network call.

Recipes

# Inspect a vault
august vault summary 0xVault --chain 8453
august vault apy 0xVault --chain 8453 --json | jq .data.currentApy

# Wallet's positions across all August vaults
august user positions 0xWallet --json \
  | jq '.data.positions[] | {vault, chainId, shares}'

# Lifetime PnL for a wallet in one vault
august user pnl 0xWallet --vault 0xVault --chain 1

# Diagnose a flaky RPC
august rpc test --json

# Per-call RPC override (no config change)
AUGUST_RPC_8453=https://my-rpc.example/v1 august vault tvl 0xVault --chain 8453

# Environment-specific config
august profile create staging --chain 8453
august profile switch staging
august config set rpcs.8453 https://staging-rpc.example/v1

Claude Code skill

Ships with a Claude Code skill that teaches Claude how to call the CLI and the companion MCP server:

august skill install
# → ~/.claude/skills/august.md

Override the destination with --dest <dir> (or CLAUDE_SKILLS_DIR). Pass --force to overwrite a divergent file.

JSON envelope

Every --json response uses the same envelope as @augustdigital/mcp:

{
  "schemaVersion": 1,
  "command": "vault.apy",
  "ok": true,
  "data": { "address": "0x…", "chainId": 8453, "currentApy": 0.1234 },
  "meta": { "chainId": 8453, "durationMs": 312, "generatedAt": "2026-05-17T…" }
}

On failure: ok: false, error: { code, message, remediation? }. Match on error.code — message text is not part of the contract.

Programmatic use

import { buildProgram } from '@augustdigital/cli';

const program = buildProgram();
await program.parseAsync(['node', 'august', 'whoami', '--json']);

buildProgram() returns the same commander tree the binary uses, so embedders (tests, MCP servers, internal tooling) can drive the CLI without spawning a child process.

Exit codes

Watch mode

points leaderboard, vault pending-redemptions, ops health, and ops redemptions accept --watch <seconds>. Human output re-renders in place; --json emits one envelope per tick (NDJSON) for piping.