Aura CLI

Node.js CLI for scaffolding new AI projects at Aura Group. Picks a project type, creates a GitHub repo from a private template via the relay API, clones it locally, collects env vars, and optionally deploys to Cloudflare.

Authentication

The CLI authenticates against the relay using OAuth 2.1 with PKCE (no client secret). Users sign in once via Microsoft Entra ID in the browser and get a long-lived refresh token.

First-time login

aura login

1. Generates a PKCE code_verifier (random 32 bytes, base64url-encoded) and derives code_challenge = SHA-256(verifier).
2. Starts a local HTTP server on 127.0.0.1:9876 to receive the redirect.
3. Opens the browser to the relay's /api/auth/oauth2/authorize endpoint with code_challenge, state, and scope=openid profile email.
4. The user signs in with Microsoft Entra ID on the relay. The relay redirects to http://127.0.0.1:9876/callback?code=...&state=....
5. CLI validates the state parameter (CSRF protection), then exchanges code + code_verifier for tokens via POST /api/auth/oauth2/token.
6. Stores access_token, refresh_token, and expiresAt in the platform-local conf store (aura-cli project name).

Login times out after 5 minutes if the browser flow is not completed.

Token refresh

Before every API call, getValidToken() checks whether the stored token expires within 60 seconds. If so, it silently refreshes via POST /api/auth/oauth2/token with grant_type=refresh_token. If the refresh fails (revoked or expired refresh token), the user is prompted to run aura login again.

Access tokens expire in 1 hour; refresh tokens expire in 30 days.

Logout

aura logout

Deletes the stored tokens from the conf store. The relay-side tokens remain valid until they expire naturally (no server-side revocation is triggered).

Token storage location

Managed by the conf package. Stored in the OS config directory:

| Platform | Location | |---|---| | macOS | ~/Library/Preferences/aura-cli/ | | Linux | ~/.config/aura-cli/ | | Windows | %APPDATA%\aura-cli\ |

Key files

| File | Purpose | |---|---| | src/services/auth/pkce.ts | Generates code_verifier, code_challenge, and state | | src/services/auth/login.ts | Full login flow, token refresh, logout | | src/services/auth/tokenStore.ts | Read/write tokens to conf store |

Constants (from @auragroup/core)

| Constant | Value | |---|---| | RELAY_URL | https://relay.auraiq.ai | | CLI_CLIENT_ID | aura-cli | | CLI_OAUTH_REDIRECT_URI | http://127.0.0.1:9876/callback | | CLI_OAUTH_CALLBACK_PORT | 9876 |

Architecture

src/
├── index.ts              # Entry point: shebang, version, hand-off to runCli()
├── cli/                  # Input layer — produces CliContext, no side effects
│   ├── args.ts           # Commander flags (--yes, --help, --version)
│   ├── prompts.ts        # @clack/prompts interactive questions
│   └── types.ts          # CliContext interface, TemplateType enum
├── orchestrator/
│   └── createProject.ts  # Sequences: auth → relay API → clone → configure → push → deploy
├── services/
│   ├── auth/             # login.ts, tokenStore.ts, pkce.ts
│   ├── github/           # clone.ts
│   └── envVars/          # collector.ts, writer.ts, definitions/{nextjs,api,mcp}.ts
├── helpers/              # logger, spinner, exec wrapper, validators

AI Library

The CLI provides access to the relay's AI resource library — a collection of reusable prompts, skills, rules, and system prompts.

Library Subcommands

aura library list

List resources from the library with optional filtering.

aura library list                                    # All resources
aura library list --type PROMPT                      # Filter by type
aura library list --tool claude                      # Filter by AI tool
aura library list --search "code review"             # Full-text search

Options:

• --type <type> — Filter by resource type: PROMPT, SKILL, RULE, or SYSTEM_PROMPT
• --tool <tool> — Filter by AI tool slug (e.g., cursor, claude)
• --search <query> — Search by title, description, or tags

Output includes resource title, type badge, like count, and slug for easy reference.

aura library get <slug>

Fetch and render a resource by slug. Supports variable substitution for prompts.

aura library get my-review-prompt                        # Get resource
aura library get my-review-prompt --var topic=security   # Set variable
aura library get my-review-prompt | pbcopy              # Pipe to clipboard (macOS)

Options:

• --var <name=value> — Set variable value (repeatable). For PROMPT types with required variables, missing values are prompted interactively

Output:

• PROMPT / SKILL: Pretty-printed content, optionally copy-to-clipboard or pipe to file
• RULE: Ask user to copy to clipboard, save to file (smart defaults: .cursorrules, CLAUDE.md, etc.), or display
• SYSTEM_PROMPT: Pretty-printed content, ready to copy

aura library create

Create a new resource interactively. Guides you through:

1. Title — Resource name
2. Type — Choose from Prompt, Skill, Rule, or System Prompt
3. Description — Optional summary
4. Visibility — Org-wide or Public
5. Content — Paste or edit the resource text
6. Variables — Define substitutable parameters (optional)
7. Tags — Add searchable tags (optional)

Build & Test

pnpm exec tsup            # Build
pnpm exec tsx src/index.ts  # Dev run
pnpm exec tsc --noEmit    # Type check
pnpm exec vitest run      # Tests

Distribution

Published to GitHub Packages (private npm). Install via:

npm install @auragroup/cli --registry=https://npm.pkg.github.com