@krunal202/apple-search-ads-cli 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 apple-search-ads-cli contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/LLM_GUIDE.md

@@ -0,0 +1,251 @@
+# LLM Guide — asa (Apple Search Ads CLI)
+
+This guide tells a language model (or any automated agent) exactly how to use `asa`.
+You can also print it at any time with:
+
+```bash
+asa llm
+```
+
+## Output contract
+
+- **Every command prints JSON to stdout.** Default is one compact line; add `--pretty` for indented JSON.
+- **Every failure prints a JSON error to stderr and exits 1:**
+
+```json
+{"error":"Not logged in","hint":"Run \"asa login\" first. See \"asa llm\" for the full guide."}
+```
+
+Error objects may include `status` (HTTP status from Apple) and `details` (Apple's raw error body).
+Always read the `hint` field — it tells you the next correct action.
+
+## Rules for agents
+
+1. **Start every session with `asa context`** (add `--live` to include current campaigns). It returns stored notes and recent mutations so you resume with full context instead of re-discovering state.
+2. Never guess IDs. Discover them with `list` commands (`asa campaigns list`, `asa adgroups list`, ...).
+3. When a command fails, read the JSON error, follow `hint`, and retry with corrected input — do not repeat the same call.
+4. Unknown command or option? Run `asa --help` or `asa <command> --help`. Suggestions are included in the error message.
+5. Any create/update accepts `--data '<json>'` to pass fields not covered by flags. `--data` is merged over flag-built values, so it wins on conflicts.
+6. `asa paste` and `asa campaigns create` default to `PAUSED` status so nothing spends money unexpectedly. Pass `--status ENABLED` explicitly to activate.
+7. After making a decision a future session should know (why a bid changed, what a test is for), record it with `asa remember "..."`.
+
+## Memory
+
+Memory is stored per org under `~/.asa/memory/<orgId>/`.
+
+```bash
+asa context [--live] [--limit 20]     # notes + recent mutations (+ live campaign list)
+asa remember "Dropped US bids to 1/3; IR/RU traffic was not converting" [--campaign <id>]
+asa memory [--limit 50]               # dump raw memory
+asa memory --clear                    # erase memory for the active org
+```
+
+Every mutating API call (create/update/delete/paste) is logged automatically with timestamp, method, path and success/failure — you do not need to log actions yourself, only *reasoning*.
+
+## Prerequisites
+
+Create credentials in **Apple Search Ads UI → Account Settings → API**. This requires a user with an **API role** (API Account Manager for read/write) — plain Account Admin does not see the create option. Invite yourself via the User Management tab if needed. Apple issues a client ID (`SEARCHADS.…`), team ID, key ID, and you upload your own ES256 (prime256v1) public key; keep the matching `.p8` private key.
+
+Note: App Store Connect keys (Issuer ID + `AuthKey_XXXX.p8`) are a different system and return `invalid_client` for this API.
+
+## Global options
+
+- `--pretty` — indented JSON instead of one compact line
+- `--org <orgId>` — override the active org for a single call (no state change)
+- `--all` — on `list` commands, auto-paginate and return every item
+
+## Authentication
+
+```bash
+asa login --client-id <id> --team-id <id> --key-id <id> --key-file ./key.p8 [--org <orgId>]
+asa whoami        # show stored credential summary + active org
+asa logout        # remove credentials, cached token and clipboard
+```
+
+- In a TTY, omitted values are prompted interactively. In a non-interactive shell all values must be flags.
+- On login, orgs are fetched automatically. With multiple orgs, pass `--org <orgId>` or pick when prompted.
+- Credentials live in `~/.asa/config.json` (mode 600). The OAuth token is cached in `~/.asa/token.json` and refreshed automatically. Override the directory with `ASA_CONFIG_DIR`.
+
+### Organizations
+
+```bash
+asa orgs list          # orgs the credentials can access
+asa orgs use <orgId>   # set the active org (sent as X-AP-Context on every call)
+```
+
+## Campaigns
+
+```bash
+asa campaigns list [--limit 20] [--offset 0]
+asa campaigns get <id>
+
+asa campaigns create \
+  --name "Summer Promo" \
+  --currency USD \
+  --adam-id 123456789 \
+  --countries US,GB \
+  [--budget 1000] [--daily-budget 50] [--status ENABLED] [--start-time 2026-09-20T00:00:00.000Z] [--end-time ...] [--data '<json>']
+
+asa campaigns update <id> [--name ...] [--status ENABLED|PAUSED] [--budget 1500 --currency USD] \
+  [--daily-budget 60 --currency USD] [--countries US,CA] [--end-time ...] [--clear-end-time] [--data '<json>']
+
+asa campaigns delete <id>
+```
+
+Notes: `--adam-id` is the numeric App Store app ID. `--budget` is the optional lifetime budget; many accounts run with `--daily-budget` only. `--currency` is required whenever a budget flag is used.
+
+## Ad groups
+
+API v5 scopes ad groups under campaigns, so every ad group command takes `--campaign`.
+
+```bash
+asa adgroups list --campaign <id> [--limit 20] [--offset 0]
+asa adgroups get <id> --campaign <id>
+
+asa adgroups create --campaign <id> --name "Generic terms" \
+  [--bid 0.50 --currency USD] [--status ENABLED] [--data '<json>']
+
+asa adgroups update <id> --campaign <id> [--name ...] [--status ...] [--bid 0.75 --currency USD] [--data '<json>']
+asa adgroups delete <id> --campaign <id>
+```
+
+`--bid` maps to the ad group's `defaultBidAmount` (CPT bid).
+
+Targeting dimensions (age, gender, device class, country, app categories...), CPA goals, and automated keywords opt-in are not flag-covered — pass them via `--data`, e.g.:
+
+```bash
+asa adgroups create --campaign 123 --name "iPhone US" --data '{"targetingDimensions":{"deviceClass":{"included":["IPHONE"]}}}'
+```
+
+## Keywords
+
+API v5 scopes targeting keywords under campaign + ad group, so every keyword command takes both `--campaign` and `--adgroup`.
+
+```bash
+asa keywords list --campaign <id> --adgroup <id> [--limit 20] [--offset 0]
+asa keywords get <id> --campaign <id> --adgroup <id>
+
+asa keywords create --campaign <id> --adgroup <id> --text "running shoes" \
+  [--match-type BROAD|EXACT] [--bid 0.40 --currency USD] [--status ENABLED]
+
+# bulk create (all keyword writes are bulk calls in v5):
+asa keywords create --campaign <id> --adgroup <id> --data '[{"text":"trail shoes","matchType":"EXACT","bidAmount":{"amount":"0.5","currency":"USD"}}]'
+
+asa keywords update <id> --campaign <id> --adgroup <id> [--bid 0.60 --currency USD] [--status PAUSED] [--data '<json>']
+asa keywords delete <id> --campaign <id> --adgroup <id>
+```
+
+## Stats / reports
+
+```bash
+asa stats <level> --start YYYY-MM-DD --end YYYY-MM-DD [options]
+```
+
+- `level`: `campaigns` | `adgroups` | `keywords` | `searchterms` | `ads`
+- `--campaign <id>` — **required for every level except `campaigns`** (API v5 scopes reports under campaigns)
+- `--granularity HOURLY|DAILY|WEEKLY|MONTHLY`
+- `--condition field=OPERATOR=value` (repeatable). Operators: `EQUALS IN NOT_IN GREATER_THAN LESS_THAN STARTSWITH CONTAINS`. Comma-separate multiple values for `IN`.
+- `--order-by field=ASCENDING|DESCENDING` (default `localSpend=DESCENDING`) — Apple requires a selector with orderBy on every report call
+- `--group-by <fields>` comma-separated, e.g. `countryOrRegion`
+- `--include-no-metrics` to include rows with no spend
+- `--data '<json>'` for any other report body fields
+
+Examples:
+
+```bash
+asa stats campaigns --start 2026-09-01 --end 2026-09-15 --granularity DAILY
+asa stats keywords --campaign 123 --start 2026-09-01 --end 2026-09-15 --condition adGroupId=EQUALS=456
+asa stats searchterms --campaign 123 --start 2026-09-01 --end 2026-09-15 --group-by countryOrRegion
+```
+
+Dates use the org's timezone (`timeZone: ORTZ`). Metric fields returned include `impressions`, `taps`, `ttr`, `spend`, `avgCPC`, `installs` (conversion fields depend on the account setup).
+
+## Apps
+
+Use this to find the `adamId` needed to create a campaign:
+
+```bash
+asa apps search "secure vpn" [--limit 10]
+```
+
+## Negative keywords
+
+Negative keywords stop your ads from matching a term. Campaign-level applies to the whole campaign; add `--adgroup` to scope to one ad group (e.g. to keep competitor terms out of a discovery group).
+
+```bash
+asa negatives list --campaign <id> [--adgroup <id>] [--all]
+
+asa negatives create --campaign <id> --text free --match-type BROAD
+asa negatives create --campaign <id> --adgroup <id> --data '[{"text":"crack","matchType":"BROAD"}]'
+
+asa negatives delete --campaign <id> [--adgroup <id>] --id <negativeKeywordId>
+asa negatives delete --campaign <id> --data '[123,456]'
+```
+
+## Copy / paste (duplicate resources)
+
+Copies are stored locally in `~/.asa/clipboard.json`. Read-only fields (IDs, timestamps, serving state) are stripped automatically.
+
+```bash
+asa copy campaign 123
+asa paste [--name "Summer Promo Q4"] [--status ENABLED]
+
+asa copy adgroup 456 --campaign 123
+asa paste [--campaign 789] [--name ...]   # --campaign pastes under a different campaign
+
+asa copy keyword 321 --campaign 123 --adgroup 456
+asa paste [--campaign 123] [--adgroup 654]  # override either parent to paste elsewhere
+```
+
+Paste always creates the resource `PAUSED` unless `--status ENABLED` is passed, appends ` - Copy` to the name unless `--name` is given, and drops `startTime`/`endTime` values that are in the past (Apple rejects them).
+
+## Typical workflows
+
+Create a full structure:
+
+```bash
+asa campaigns create --name "Brand" --daily-budget 50 --currency USD --adam-id 123456789 --countries US
+# → read the new campaign id from the JSON response
+asa adgroups create --campaign <campaignId> --name "Core" --bid 0.50 --currency USD
+asa keywords create --campaign <campaignId> --adgroup <adgroupId> --data '[{"text":"my app","matchType":"EXACT"},{"text":"my app pro","matchType":"BROAD"}]'
+asa campaigns update <campaignId> --status ENABLED
+```
+
+Daily performance check:
+
+```bash
+asa stats campaigns --start <today-7d> --end <today> --granularity DAILY
+asa campaigns update <id> --status PAUSED   # if over-performing budget
+```
+
+Search-term mining loop (the core optimization cycle):
+
+```bash
+# 1. see what queries triggered ads in the discovery ad group's campaign
+asa stats searchterms --campaign <campaignId> --start <date> --end <date>
+# 2. promote winners into the exact ad group
+asa keywords create --campaign <campaignId> --adgroup <exactAdgroupId> --text "<winner>" --match-type EXACT
+# 3. block them in discovery so it keeps finding new terms, and block junk everywhere
+asa negatives create --campaign <campaignId> --adgroup <discoveryAdgroupId> --text "<winner>" --match-type EXACT
+asa negatives create --campaign <campaignId> --text "<junk term>" --match-type BROAD
+```
+
+Duplicate a campaign into another market:
+
+```bash
+asa copy campaign 123
+asa paste --name "Brand - UK"
+asa campaigns update <newId> --countries GB --data '{}'
+```
+
+## Troubleshooting
+
+| Symptom | Fix |
+|---|---|
+| `{"error":"Not logged in"...}` | Run `asa login` with all flags |
+| HTTP 401 | Credentials wrong or key revoked — re-run `asa login` |
+| HTTP 400 `invalid_client` on login | Wrong credential system: App Store Connect Issuer IDs don't work — use ASA UI → Account Settings → API credentials (`SEARCHADS.…` client ID) with an API-role user |
+| HTTP 403 | Wrong org — `asa orgs list` then `asa orgs use <orgId>` |
+| HTTP 404 | Stale ID — re-list the parent resource |
+| HTTP 429 | Rate limited — wait and retry |
+| `unknown command 'xyz'` | Check the suggestion in the error, or run `asa --help` |

package/README.md

@@ -0,0 +1,84 @@
+# apple-search-ads-cli
+
+A small, LLM-friendly CLI for the [Apple Search Ads API](https://developer.apple.com/documentation/apple_search_ads) (v5). JSON in, JSON out, structured errors with hints — built to be driven by humans and language-model agents alike.
+
+## Install
+
+```bash
+npm i -g @krunal202/apple-search-ads-cli   # exposes the `asa` binary
+```
+
+Or from source:
+
+```bash
+npm install
+npm link
+```
+
+Requires Node.js ≥ 18. Single runtime dependency: `commander`.
+
+## Quickstart
+
+```bash
+# 1. Get API credentials: Apple Search Ads → Account Settings → API (client ID, team ID, key ID, .p8 key)
+asa login --client-id <id> --team-id <id> --key-id <id> --key-file ./AuthKey.p8
+
+asa orgs list && asa orgs use <orgId>
+
+asa campaigns list --pretty
+asa campaigns create --name "Launch" --budget 1000 --currency USD --adam-id 123456789 --countries US
+asa adgroups create --campaign <id> --name "Core" --bid 0.50 --currency USD
+asa keywords create --campaign <id> --adgroup <id> --text "my app" --match-type EXACT
+
+asa stats campaigns --start 2026-09-01 --end 2026-09-15 --granularity DAILY --pretty
+
+asa copy campaign <id>
+asa paste --name "Launch - Q4"
+
+asa logout
+```
+
+## LLM integration
+
+- `asa llm` prints the complete machine-readable usage guide (also in [LLM_GUIDE.md](LLM_GUIDE.md)).
+- Output is single-line JSON by default (`--pretty` for humans).
+- Errors are structured JSON on stderr with a `hint` field describing the corrective action; unknown commands include "did you mean" suggestions.
+- Every create/update accepts `--data '<json>'` for fields not covered by flags.
+
+### Memory for agents
+
+`asa` remembers what happened so an LLM starting a fresh session can pick up context:
+
+- Every mutating API call is logged automatically per org (`~/.asa/memory/<orgId>/activity.jsonl`).
+- `asa remember "note" [--campaign <id>]` stores decisions and rationale.
+- `asa context [--live]` prints notes + recent activity (+ current campaigns) — the recommended first command of any agent session.
+- `asa memory` / `asa memory --clear` inspects or erases the store.
+
+## Layout
+
+```
+bin/asa.js            executable entry
+src/cli.js            program wiring, error handling
+src/config.js         ~/.asa credential/token/clipboard storage
+src/api/auth.js       ES256 client-secret JWT + OAuth token exchange
+src/api/client.js     authenticated fetch wrapper (X-AP-Context, error mapping)
+src/commands/         login/logout/orgs, campaigns, adgroups, keywords, negatives,
+                      apps, stats, copy/paste, llm guide
+test/                 node:test unit tests (npm test)
+```
+
+Not yet covered by the CLI: ad creative / custom product page management and budget orders (campaigns are served with the default product page ad).
+
+## License
+
+MIT
+
+## Sponsors
+
+Maintaining API coverage as Apple evolves the Search Ads API takes ongoing work. If this CLI saves you time, consider sponsoring:
+
+- **[Buy Me a Coffee](https://buymeacoffee.com/krunaldoshi)**
+- GitHub Sponsors (button on the repo page once enabled)
+- Questions or sponsorship inquiries: [@krunaldoshi202](https://twitter.com/krunaldoshi202) on X
+
+Sponsors can be listed here and in release notes; reach out for logo placement or priority feature requests.

package/bin/asa.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import '../src/cli.js';

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "@krunal202/apple-search-ads-cli",
+  "version": "0.1.0",
+  "description": "LLM-friendly CLI for the Apple Search Ads API",
+  "type": "module",
+  "bin": {
+    "asa": "./bin/asa.js"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "files": [
+    "bin",
+    "src",
+    "LLM_GUIDE.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/krunal202/apple-search-ads-cli.git"
+  },
+  "bugs": "https://github.com/krunal202/apple-search-ads-cli/issues",
+  "homepage": "https://github.com/krunal202/apple-search-ads-cli#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT",
+  "keywords": [
+    "apple-search-ads",
+    "cli",
+    "llm",
+    "ads"
+  ],
+  "dependencies": {
+    "commander": "^12.1.0"
+  }
+}

package/src/api/auth.js

@@ -0,0 +1,60 @@
+import crypto from 'node:crypto';
+import { getCredentials, readJson, writeJson } from '../config.js';
+import { AsaError } from '../errors.js';
+
+const TOKEN_URL = 'https://appleid.apple.com/auth/oauth2/token';
+const JWT_TTL_SECONDS = 60 * 60 * 24 * 30;
+
+export function buildClientSecret({ clientId, teamId, keyId, privateKey }) {
+  const now = Math.floor(Date.now() / 1000);
+  const header = { alg: 'ES256', kid: keyId, typ: 'JWT' };
+  const payload = {
+    iss: teamId,
+    iat: now,
+    exp: now + JWT_TTL_SECONDS,
+    aud: 'https://appleid.apple.com',
+    sub: clientId,
+  };
+  const encode = (obj) => Buffer.from(JSON.stringify(obj)).toString('base64url');
+  const signingInput = `${encode(header)}.${encode(payload)}`;
+  const signature = crypto.sign('sha256', Buffer.from(signingInput), {
+    key: privateKey,
+    dsaEncoding: 'ieee-p1363',
+  });
+  return `${signingInput}.${signature.toString('base64url')}`;
+}
+
+async function fetchAccessToken(credentials) {
+  const body = new URLSearchParams({
+    grant_type: 'client_credentials',
+    client_id: credentials.clientId,
+    client_secret: buildClientSecret(credentials),
+    scope: 'searchadsorg',
+  });
+  const res = await fetch(TOKEN_URL, { method: 'POST', body });
+  const data = await res.json().catch(() => ({}));
+  if (!res.ok || !data.access_token) {
+    throw new AsaError('Failed to obtain an Apple access token', {
+      status: res.status,
+      details: data,
+      hint: 'Check client ID, team ID, key ID and private key with "asa login".',
+    });
+  }
+  return {
+    accessToken: data.access_token,
+    expiresAt: Date.now() + (Number(data.expires_in ?? 3600) - 60) * 1000,
+  };
+}
+
+export async function getAccessToken() {
+  const cached = readJson('token.json');
+  if (cached && cached.expiresAt > Date.now()) return cached.accessToken;
+
+  const credentials = getCredentials();
+  if (!credentials) {
+    throw new AsaError('Not logged in', { hint: 'Run "asa login" first. See "asa llm" for the full guide.' });
+  }
+  const token = await fetchAccessToken(credentials);
+  writeJson('token.json', token);
+  return token.accessToken;
+}

package/src/api/client.js

@@ -0,0 +1,79 @@
+import { getOrgId } from '../config.js';
+import { AsaError } from '../errors.js';
+import { logActivity } from '../memory.js';
+import { getAccessToken } from './auth.js';
+
+const BASE_URL = 'https://api.searchads.apple.com/api/v5';
+
+const STATUS_HINTS = {
+  400: 'The request body or parameters are invalid. Check the command options or pass a raw body with --data.',
+  401: 'Authentication failed. Run "asa login" to refresh credentials.',
+  403: 'No access to this resource. Check the active org with "asa orgs list" and switch with "asa orgs use <orgId>".',
+  404: 'Resource not found. Verify the ID, e.g. with "asa campaigns list".',
+  429: 'Rate limited by Apple. Wait a moment and retry.',
+};
+
+let orgOverride;
+
+export function setOrgOverride(orgId) {
+  orgOverride = orgId ? Number(orgId) : undefined;
+}
+
+export async function api(method, resource, { body, query, orgId } = {}) {
+  const token = await getAccessToken();
+  const org = getOrgId(orgId ?? orgOverride);
+  if (!org && resource !== '/acls') {
+    throw new AsaError('No organization selected', {
+      hint: 'Run "asa orgs list" then "asa orgs use <orgId>".',
+    });
+  }
+
+  const url = new URL(BASE_URL + resource);
+  for (const [key, value] of Object.entries(query ?? {})) {
+    if (value !== undefined && value !== null) url.searchParams.set(key, String(value));
+  }
+
+  const headers = { Authorization: `Bearer ${token}` };
+  if (org) headers['X-AP-Context'] = `orgId=${org}`;
+  if (body !== undefined) headers['Content-Type'] = 'application/json';
+
+  const res = await fetch(url, {
+    method,
+    headers,
+    body: body !== undefined ? JSON.stringify(body) : undefined,
+  });
+
+  const text = await res.text();
+  let data;
+  try {
+    data = JSON.parse(text);
+  } catch {
+    data = text;
+  }
+
+  const isMutation = method !== 'GET' && !resource.startsWith('/reports');
+  if (!res.ok) {
+    if (isMutation) logActivity({ method, resource, ok: false, status: res.status });
+    throw new AsaError(`Apple Search Ads API error (HTTP ${res.status})`, {
+      status: res.status,
+      details: data,
+      hint: STATUS_HINTS[res.status],
+    });
+  }
+  if (isMutation) logActivity({ method, resource, ok: true });
+  return data;
+}
+
+export async function apiAll(resource, { query, pageSize = 1000 } = {}) {
+  const items = [];
+  let offset = 0;
+  for (;;) {
+    const page = await api('GET', resource, { query: { ...query, limit: pageSize, offset } });
+    const batch = page.data ?? [];
+    items.push(...batch);
+    const total = page.pagination?.totalResults ?? items.length;
+    if (items.length >= total || batch.length === 0) break;
+    offset += batch.length;
+  }
+  return items;
+}

package/src/cli.js

@@ -0,0 +1,70 @@
+import { Command } from 'commander';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { setOrgOverride } from './api/client.js';
+import { registerAdGroups } from './commands/adgroups.js';
+import { registerApps } from './commands/apps.js';
+import { registerAuth, registerOrgs } from './commands/auth.js';
+import { registerCampaigns } from './commands/campaigns.js';
+import { registerClipboard } from './commands/clipboard.js';
+import { printGuide } from './commands/guide.js';
+import { registerKeywords } from './commands/keywords.js';
+import { registerMemory } from './commands/memory.js';
+import { registerNegatives } from './commands/negatives.js';
+import { registerStats } from './commands/stats.js';
+import { AsaError } from './errors.js';
+import { printError, setPretty } from './output.js';
+
+const pkg = JSON.parse(readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf8'));
+
+const program = new Command();
+program
+  .name('asa')
+  .description('CLI for the Apple Search Ads API. Output is JSON (one line) by default; add --pretty for indented JSON.\nRun "asa llm" for the full machine-readable usage guide.')
+  .version(pkg.version)
+  .option('--pretty', 'pretty-print JSON output')
+  .option('--org <orgId>', 'override the active organization for this call')
+  .showSuggestionAfterError(true);
+
+program.hook('preAction', (cmd) => {
+  const opts = cmd.optsWithGlobals();
+  setPretty(opts.pretty);
+  setOrgOverride(opts.org);
+});
+
+registerAuth(program);
+registerOrgs(program);
+registerCampaigns(program);
+registerAdGroups(program);
+registerKeywords(program);
+registerNegatives(program);
+registerApps(program);
+registerStats(program);
+registerClipboard(program);
+registerMemory(program);
+
+program.command('llm').description('Print the full LLM usage guide').action(printGuide);
+
+function configureRecursive(cmd) {
+  cmd.configureOutput({ writeErr: () => {} });
+  cmd.exitOverride();
+  for (const sub of cmd.commands) configureRecursive(sub);
+}
+configureRecursive(program);
+
+try {
+  await program.parseAsync(process.argv);
+} catch (err) {
+  if (err.code === 'commander.helpDisplayed' || err.code === 'commander.version') {
+    process.exit(0);
+  }
+  if (typeof err.code === 'string' && err.code.startsWith('commander.')) {
+    printError(new AsaError(err.message.trim(), {
+      hint: 'Run "asa --help" to list commands, "asa <command> --help" for options, or "asa llm" for the full guide.',
+    }));
+  } else {
+    printError(err);
+  }
+  process.exit(1);
+}