Getting started
Sign in, then ask the Advisor org-scoped architecture questions grounded in your team's ADRs — the full command reference for the actual CLI.
Quick Start
actual connects your terminal to the Advisor: sign in once, then ask org-scoped architecture questions and get answers grounded in your team's Architectural Decision Records (ADRs).
Install
Choose your preferred install method:
# Homebrew (macOS & Linux) brew install actual-software/actual/actual # Zero-install (Node required) — run any command with npx npx @actualai/actual <command>
Sign in
Authenticate with browser-based OAuth. This establishes your Actual AI platform identity; credentials are stored locally and tokens are never printed.
actual login
Ask the Advisor
From anywhere, ask an architecture question:
actual advisor "Which router do we use for new Next.js pages?"
The Advisor answers from your organization's ADRs and lists the records it drew on, each with a confidence score.
Commands
The advisor commands and their flags.
actual login
Sign in to your Actual AI account with browser-based OAuth. This establishes your platform identity and is the first step before actual advisor. The sign-in requests the adr:query and adr:review scopes; credentials are stored locally and tokens are never printed.
# Sign in via browser OAuth actual login # Print the sign-in URL instead of opening a browser (e.g. over SSH) actual login --no-browser
| Flag | Type | Description |
|---|---|---|
--org <ORG_ID> | string | Organization to sign in to. Required for accounts in more than one org; single-org accounts are auto-selected. |
--no-browser | bool | Print the sign-in URL instead of opening a browser — useful over SSH. |
--api-url <URL> | string | Auth server base URL. Falls back to ACTUAL_AUTH_URL. |
Example output
Opening your browser to sign in to Actual AI… If it doesn't open, visit this URL: https://app.actual.ai/authorize?… ✔ Signed in to Actual AI Organization: org_3f1a… Account: acct_2c00… Member: mbr_8a91…
actual advisor
Ask the Advisor an org-scoped architecture question and get an answer grounded in your team's ADRs. Requires a prior actual login. The Advisor shows a thinking… indicator while it works, then prints the answer followed by the related ADRs it drew on, each with a confidence score. Queries run against the production api-service by default.
actual advisor "<question>"
| Flag | Type | Description |
|---|---|---|
--org <ORG> | string | Organization to scope the query to. Defaults to the signed-in org. |
--repo <REPO> | string | Scope the query to one connected repository (UUID). Omitted, the query runs at org level. |
--api-url <URL> | string | Advisor API base URL. Falls back to ACTUAL_API_URL, else the production api-service. |
Examples
# Ask an org-scoped architecture question actual advisor "Which router do we use for new Next.js pages?" # Scope the question to one connected repo actual advisor "What is our API error-handling convention?" --repo <REPO_UUID>
Example output
Output for actual advisor "How should authentication and authorization be handled?", trimmed to the first matched ADR:
advisor thinking… ## Relevant ADRs (5 found) ### ADR: Standardize External API Client Initialization with Explicit Credential Management for Applications **Policy:** Applications must implement explicit credential management at external service boundaries with dependency injection of authenticated clients. **Instructions:** Create clients in designated initialization modules or script entry points with explicit credential management through centralized secrets systems. Pass client instances through function signatures using dependency injection rather than creating clients inline or using global singletons… **Scope:** In scope: All Python scripts and modules that interact with external HTTP APIs, integration with third-party services (Slack, GitHub, Claude, etc.), authentication and authorization flows for external services… Out of scope: Internal service-to-service communication, database connection management, file system access… **Confidence:** High _(4 more related ADRs returned)_
actual whoami
Show the signed-in Actual AI account, organization, member id, and granted scopes. Reads the locally cached credentials with no network call, and errors when you are signed out.
actual whoami
Example output
✔ Signed in to Actual AI Organization: org_3f1a… Account: acct_2c00… Member: mbr_8a91… Scopes: openid profile offline_access adr:query adr:review
When you are signed out, it prints an error and exits non-zero:
╭─ Error ───────────────────────────────────╮ │ │ │ Error: Not signed in to Actual AI │ │ │ │ Fix: actual login │ │ │ ╰───────────────────────────────────────────╯
actual logout
Sign out and clear local credentials. It makes a best-effort attempt to revoke the session server-side, then always removes the local tokens, even offline, so the machine is never left holding a credential you meant to drop.
actual logout
Example output
✔ Signed out of Actual AI.