# actual CLI — Getting Started & Command Reference

> 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).

## Quick Start

```bash
# 1. Install
brew install actual-software/actual/actual
# or zero-install (Node required) — run any command with npx:
npx @actualai/actual <command>

# 2. Sign in via browser OAuth
actual login

# 3. Ask the Advisor — from anywhere
actual advisor "Which router do we use for new Next.js pages?"
```

---

## Commands

### 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.

```bash
# 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
```

Flags:

| 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:**

```text
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, grounded in your team's ADRs. Requires a prior actual login. It 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.

```bash
actual advisor "<question>"
```

Flags:

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

```bash
# 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**, for `actual advisor "How should authentication and authorization be handled?"` (trimmed to the first matched ADR):

```text
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 locally cached credentials with no network call, and errors when you are signed out.

```bash
actual whoami
```

**Example output:**

```text
✔ Signed in to Actual AI
  Organization:  org_3f1a…
  Account:       acct_2c00…
  Member:        mbr_8a91…
  Scopes:        openid profile offline_access adr:query adr:review
```

When signed out, it prints an error and exits non-zero:

```text
╭─ 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.

```bash
actual logout
```

**Example output:**

```text
✔ Signed out of Actual AI.
```