[AI] Add @actual-app/cli package

New CLI tool wrapping the full @actual-app/api surface for interacting with Actual Budget from the command line. Connects to a sync server and supports all CRUD operations across accounts, budgets, categories, transactions, payees, tags, rules, schedules, and AQL queries.
2026-04-28 10:33:02 -05:00 · 2026-03-13 23:54:31 +00:00
parent 9c61cfc145
commit c4de834f98
40 changed files with 2692 additions and 4 deletions
--- a/.github/workflows/build.yml
+++ b/.github/workflows/build.yml
@@ -81,6 +81,24 @@ jobs:
          name: build-stats
          path: packages/desktop-client/build-stats

+  cli:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - name: Set up environment
+        uses: ./.github/actions/setup
+        with:
+          download-translations: 'false'
+      - name: Build CLI
+        run: cd packages/cli && yarn build
+      - name: Create package tgz
+        run: cd packages/cli && yarn pack && mv package.tgz actual-cli.tgz
+      - name: Upload Build
+        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        with:
+          name: actual-cli
+          path: packages/cli/actual-cli.tgz
+
  server:
    runs-on: ubuntu-latest
    steps:
--- a/.github/workflows/publish-nightly-npm-packages.yml
+++ b/.github/workflows/publish-nightly-npm-packages.yml
@@ -23,11 +23,13 @@ jobs:
          NEW_WEB_VERSION=$(node ./packages/ci-actions/bin/get-next-package-version.js --package-json ./packages/desktop-client/package.json --type nightly)
          NEW_SYNC_VERSION=$(node ./packages/ci-actions/bin/get-next-package-version.js --package-json ./packages/sync-server/package.json --type nightly)
          NEW_API_VERSION=$(node ./packages/ci-actions/bin/get-next-package-version.js --package-json ./packages/api/package.json --type nightly)
+          NEW_CLI_VERSION=$(node ./packages/ci-actions/bin/get-next-package-version.js --package-json ./packages/cli/package.json --type nightly)

          # Set package versions
          npm version $NEW_WEB_VERSION --no-git-tag-version --workspace=@actual-app/web --no-workspaces-update
          npm version $NEW_SYNC_VERSION --no-git-tag-version --workspace=@actual-app/sync-server --no-workspaces-update
          npm version $NEW_API_VERSION --no-git-tag-version --workspace=@actual-app/api --no-workspaces-update
+          npm version $NEW_CLI_VERSION --no-git-tag-version --workspace=@actual-app/cli --no-workspaces-update

      - name: Yarn install
        run: |
@@ -48,6 +50,13 @@ jobs:
        run: |
          yarn workspace @actual-app/api pack --filename @actual-app/api.tgz

+      - name: Build CLI
+        run: yarn workspace @actual-app/cli build
+
+      - name: Pack the cli package
+        run: |
+          yarn workspace @actual-app/cli pack --filename @actual-app/cli.tgz
+
      - name: Upload package artifacts
        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
        with:
@@ -56,6 +65,7 @@ jobs:
            packages/desktop-client/@actual-app/web.tgz
            packages/sync-server/@actual-app/sync-server.tgz
            packages/api/@actual-app/api.tgz
+            packages/cli/@actual-app/cli.tgz

  publish:
    runs-on: ubuntu-latest
@@ -93,3 +103,9 @@ jobs:
          npm publish api/@actual-app/api.tgz --access public --tag nightly
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Publish CLI
+        run: |
+          npm publish cli/@actual-app/cli.tgz --access public --tag nightly
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
--- a/.github/workflows/publish-npm-packages.yml
+++ b/.github/workflows/publish-npm-packages.yml
@@ -31,6 +31,13 @@ jobs:
        run: |
          yarn workspace @actual-app/api pack --filename @actual-app/api.tgz

+      - name: Build CLI
+        run: yarn workspace @actual-app/cli build
+
+      - name: Pack the cli package
+        run: |
+          yarn workspace @actual-app/cli pack --filename @actual-app/cli.tgz
+
      - name: Upload package artifacts
        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
        with:
@@ -39,6 +46,7 @@ jobs:
            packages/desktop-client/@actual-app/web.tgz
            packages/sync-server/@actual-app/sync-server.tgz
            packages/api/@actual-app/api.tgz
+            packages/cli/@actual-app/cli.tgz

  publish:
    runs-on: ubuntu-latest
@@ -76,3 +84,9 @@ jobs:
          npm publish api/@actual-app/api.tgz --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Publish CLI
+        run: |
+          npm publish cli/@actual-app/cli.tgz --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
--- a/.gitignore
+++ b/.gitignore
@@ -81,3 +81,10 @@ build/

 *storybook.log
 storybook-static
+
+# cli config when testing locally
+.actualrc.json
+.actualrc
+.actualrc.yaml
+.actualrc.yml
+actual.config.js
--- a/lage.config.js
+++ b/lage.config.js
@@ -17,6 +17,7 @@ module.exports = {
    },
    build: {
      type: 'npmScript',
+      dependsOn: ['^build'],
      cache: true,
      options: {
        outputGlob: ['lib-dist/**', 'dist/**', 'build/**'],
--- a/package.json
+++ b/package.json
@@ -34,12 +34,14 @@
    "start:browser-backend": "yarn workspace loot-core watch:browser",
    "start:browser-frontend": "yarn workspace @actual-app/web start:browser",
    "start:storybook": "yarn workspace @actual-app/components start:storybook",
+    "build": "lage build",
    "build:browser-backend": "yarn workspace loot-core build:browser",
    "build:server": "yarn build:browser && yarn workspace @actual-app/sync-server build",
    "build:browser": "./bin/package-browser",
    "build:desktop": "./bin/package-electron",
    "build:plugins-service": "yarn workspace plugins-service build",
    "build:api": "yarn workspace @actual-app/api build",
+    "build:cli": "yarn build --scope=@actual-app/cli",
    "build:docs": "yarn workspace docs build",
    "build:storybook": "yarn workspace @actual-app/components build:storybook",
    "deploy:docs": "yarn workspace docs deploy",
--- a/packages/api/app/query.js
+++ b/packages/api/app/query.js
@@ -1,4 +1,7 @@
 class Query {
+  /** @type {import('loot-core/shared/query').QueryState} */
+  state;
+
  constructor(state) {
    this.state = {
      filterExpressions: state.filterExpressions || [],
--- a/packages/cli/.gitignore
+++ b/packages/cli/.gitignore
@@ -0,0 +1,7 @@
+dist
+coverage
+.actualrc.json
+.actualrc
+.actualrc.yaml
+.actualrc.yml
+actual.config.js
--- a/packages/cli/README.md
+++ b/packages/cli/README.md
@@ -0,0 +1,155 @@
+# @actual-app/cli
+
+> **WARNING:** This CLI is experimental.
+
+Command-line interface for [Actual Budget](https://actualbudget.org). Query and modify your budget data from the terminal — accounts, transactions, categories, payees, rules, schedules, and more.
+
+> **Note:** This CLI connects to a running [Actual sync server](https://actualbudget.org/docs/install/). It does not operate on local budget files directly.
+
+## Installation
+
+```bash
+npm install -g @actual-app/cli
+```
+
+Requires Node.js >= 22.
+
+## Quick Start
+
+```bash
+# Set connection details
+export ACTUAL_SERVER_URL=http://localhost:5006
+export ACTUAL_PASSWORD=your-password
+export ACTUAL_BUDGET_ID=your-sync-id   # Found in Settings → Advanced → Sync ID
+
+# List your accounts
+actual accounts list
+
+# Check a balance
+actual accounts balance <account-id>
+
+# View this month's budget
+actual budgets month 2026-03
+```
+
+## Configuration
+
+Configuration is resolved in this order (highest priority first):
+
+1. **CLI flags** (`--server-url`, `--password`, etc.)
+2. **Environment variables**
+3. **Config file** (via [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig))
+4. **Defaults** (`dataDir` defaults to `~/.actual-cli/data`)
+
+### Environment Variables
+
+| Variable               | Description                                   |
+| ---------------------- | --------------------------------------------- |
+| `ACTUAL_SERVER_URL`    | URL of the Actual sync server (required)      |
+| `ACTUAL_PASSWORD`      | Server password (required unless using token) |
+| `ACTUAL_SESSION_TOKEN` | Session token (alternative to password)       |
+| `ACTUAL_BUDGET_ID`     | Budget Sync ID (required for most commands)   |
+| `ACTUAL_DATA_DIR`      | Local directory for cached budget data        |
+
+### Config File
+
+Create an `.actualrc.json` (or `.actualrc`, `.actualrc.yaml`, `actual.config.js`):
+
+```json
+{
+  "serverUrl": "http://localhost:5006",
+  "password": "your-password",
+  "budgetId": "1cfdbb80-6274-49bf-b0c2-737235a4c81f"
+}
+```
+
+**Security:** Do not store plaintext passwords in config files (e.g. `.actualrc.json`, `.actualrc`, `.actualrc.yaml`, `actual.config.js`). Add these files to `.gitignore` if they contain secrets. Prefer the `ACTUAL_SESSION_TOKEN` environment variable instead of the `password` field. See [Environment Variables](#environment-variables) for using a session token.
+
+### Global Flags
+
+| Flag                      | Description                                     |
+| ------------------------- | ----------------------------------------------- |
+| `--server-url <url>`      | Server URL                                      |
+| `--password <pw>`         | Server password                                 |
+| `--session-token <token>` | Session token                                   |
+| `--budget-id <id>`        | Budget Sync ID                                  |
+| `--data-dir <path>`       | Data directory                                  |
+| `--format <format>`       | Output format: `json` (default), `table`, `csv` |
+| `--quiet`                 | Suppress informational stderr messages          |
+
+## Commands
+
+| Command           | Description                    |
+| ----------------- | ------------------------------ |
+| `accounts`        | Manage accounts                |
+| `budgets`         | Manage budgets and allocations |
+| `categories`      | Manage categories              |
+| `category-groups` | Manage category groups         |
+| `transactions`    | Manage transactions            |
+| `payees`          | Manage payees                  |
+| `tags`            | Manage tags                    |
+| `rules`           | Manage transaction rules       |
+| `schedules`       | Manage scheduled transactions  |
+| `query`           | Run an ActualQL query          |
+| `server`          | Server utilities and lookups   |
+
+Run `actual <command> --help` for subcommands and options.
+
+### Examples
+
+```bash
+# List all accounts (as a table)
+actual accounts list --format table
+
+# Find an entity ID by name
+actual server get-id --type accounts --name "Checking"
+
+# Add a transaction (amount in integer cents: -2500 = -$25.00)
+actual transactions add --account <id> \
+  --data '[{"date":"2026-03-14","amount":-2500,"payee_name":"Coffee Shop"}]'
+
+# Export transactions to CSV
+actual transactions list --account <id> \
+  --start 2026-01-01 --end 2026-12-31 --format csv > transactions.csv
+
+# Set budget amount ($500 = 50000 cents)
+actual budgets set-amount --month 2026-03 --category <id> --amount 50000
+
+# Run an ActualQL query
+actual query run --table transactions \
+  --select "date,amount,payee" --filter '{"amount":{"$lt":0}}' --limit 10
+```
+
+### Amount Convention
+
+All monetary amounts are **integer cents**:
+
+| CLI Value | Dollar Amount |
+| --------- | ------------- |
+| `5000`    | $50.00        |
+| `-12350`  | -$123.50      |
+
+## Running Locally (Development)
+
+If you're working on the CLI within the monorepo:
+
+```bash
+# 1. Build the CLI
+yarn build:cli
+
+# 2. Start a local sync server (in a separate terminal)
+yarn start:server-dev
+
+# 3. Open http://localhost:5006 in your browser, create a budget,
+#    then find the Sync ID in Settings → Advanced → Sync ID
+
+# 4. Run the CLI directly from the build output
+ACTUAL_SERVER_URL=http://localhost:5006 \
+ACTUAL_PASSWORD=your-password \
+ACTUAL_BUDGET_ID=your-sync-id \
+node packages/cli/dist/cli.js accounts list
+
+# Or use a shorthand alias for convenience
+alias actual-dev="node $(pwd)/packages/cli/dist/cli.js"
+actual-dev budgets list
+```
--- a/packages/cli/package.json
+++ b/packages/cli/package.json
@@ -0,0 +1,34 @@
+{
+  "name": "@actual-app/cli",
+  "version": "26.3.0",
+  "description": "CLI for Actual Budget",
+  "license": "MIT",
+  "bin": {
+    "actual": "./dist/cli.js",
+    "actual-cli": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "scripts": {
+    "build": "vite build",
+    "test": "vitest --run",
+    "typecheck": "tsgo -b"
+  },
+  "dependencies": {
+    "@actual-app/api": "workspace:*",
+    "cli-table3": "^0.6.5",
+    "commander": "^13.0.0",
+    "cosmiconfig": "^9.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.19.10",
+    "@typescript/native-preview": "^7.0.0-dev.20260309.1",
+    "vite": "^7.3.1",
+    "vitest": "^4.0.18"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}
--- a/packages/cli/src/commands/accounts.test.ts
+++ b/packages/cli/src/commands/accounts.test.ts
@@ -0,0 +1,205 @@
+import { Command } from 'commander';
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('@actual-app/api', () => ({
+  getAccounts: vi.fn().mockResolvedValue([]),
+  createAccount: vi.fn().mockResolvedValue('new-id'),
+  updateAccount: vi.fn().mockResolvedValue(undefined),
+  closeAccount: vi.fn().mockResolvedValue(undefined),
+  reopenAccount: vi.fn().mockResolvedValue(undefined),
+  deleteAccount: vi.fn().mockResolvedValue(undefined),
+  getAccountBalance: vi.fn().mockResolvedValue(10000),
+}));
+
+vi.mock('../connection', () => ({
+  withConnection: vi.fn((_opts, fn) => fn()),
+}));
+
+vi.mock('../output', () => ({
+  printOutput: vi.fn(),
+}));
+
+const api = await import('@actual-app/api');
+const { printOutput } = await import('../output');
+const { registerAccountsCommand } = await import('./accounts');
+
+function createProgram(): Command {
+  const program = new Command();
+  program.option('--format <format>');
+  program.option('--server-url <url>');
+  program.option('--password <pw>');
+  program.option('--session-token <token>');
+  program.option('--budget-id <id>');
+  program.option('--data-dir <dir>');
+  program.option('--quiet');
+  program.exitOverride();
+  registerAccountsCommand(program);
+  return program;
+}
+
+async function run(args: string[]) {
+  const program = createProgram();
+  await program.parseAsync(['node', 'test', ...args]);
+}
+
+describe('accounts commands', () => {
+  let stderrSpy: ReturnType<typeof vi.spyOn>;
+  let stdoutSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    stderrSpy = vi
+      .spyOn(process.stderr, 'write')
+      .mockImplementation(() => true);
+    stdoutSpy = vi
+      .spyOn(process.stdout, 'write')
+      .mockImplementation(() => true);
+  });
+
+  afterEach(() => {
+    stderrSpy.mockRestore();
+    stdoutSpy.mockRestore();
+  });
+
+  describe('list', () => {
+    it('calls api.getAccounts and prints result', async () => {
+      const accounts = [{ id: '1', name: 'Checking' }];
+      vi.mocked(api.getAccounts).mockResolvedValue(accounts as never);
+
+      await run(['accounts', 'list']);
+
+      expect(api.getAccounts).toHaveBeenCalled();
+      expect(printOutput).toHaveBeenCalledWith(accounts, undefined);
+    });
+
+    it('passes format option to printOutput', async () => {
+      vi.mocked(api.getAccounts).mockResolvedValue([] as never);
+
+      await run(['--format', 'csv', 'accounts', 'list']);
+
+      expect(printOutput).toHaveBeenCalledWith([], 'csv');
+    });
+  });
+
+  describe('create', () => {
+    it('passes name and defaults to api.createAccount', async () => {
+      await run(['accounts', 'create', '--name', 'Savings']);
+
+      expect(api.createAccount).toHaveBeenCalledWith(
+        { name: 'Savings', offbudget: false },
+        0,
+      );
+      expect(printOutput).toHaveBeenCalledWith({ id: 'new-id' }, undefined);
+    });
+
+    it('passes offbudget and balance options', async () => {
+      await run([
+        'accounts',
+        'create',
+        '--name',
+        'Investments',
+        '--offbudget',
+        '--balance',
+        '50000',
+      ]);
+
+      expect(api.createAccount).toHaveBeenCalledWith(
+        { name: 'Investments', offbudget: true },
+        50000,
+      );
+    });
+  });
+
+  describe('update', () => {
+    it('passes fields to api.updateAccount', async () => {
+      await run(['accounts', 'update', 'acct-1', '--name', 'NewName']);
+
+      expect(api.updateAccount).toHaveBeenCalledWith('acct-1', {
+        name: 'NewName',
+      });
+      expect(printOutput).toHaveBeenCalledWith(
+        { success: true, id: 'acct-1' },
+        undefined,
+      );
+    });
+  });
+
+  describe('close', () => {
+    it('passes transfer options to api.closeAccount', async () => {
+      await run([
+        'accounts',
+        'close',
+        'acct-1',
+        '--transfer-account',
+        'acct-2',
+      ]);
+
+      expect(api.closeAccount).toHaveBeenCalledWith(
+        'acct-1',
+        'acct-2',
+        undefined,
+      );
+    });
+
+    it('passes transfer category', async () => {
+      await run([
+        'accounts',
+        'close',
+        'acct-1',
+        '--transfer-category',
+        'cat-1',
+      ]);
+
+      expect(api.closeAccount).toHaveBeenCalledWith(
+        'acct-1',
+        undefined,
+        'cat-1',
+      );
+    });
+  });
+
+  describe('reopen', () => {
+    it('calls api.reopenAccount', async () => {
+      await run(['accounts', 'reopen', 'acct-1']);
+
+      expect(api.reopenAccount).toHaveBeenCalledWith('acct-1');
+      expect(printOutput).toHaveBeenCalledWith(
+        { success: true, id: 'acct-1' },
+        undefined,
+      );
+    });
+  });
+
+  describe('delete', () => {
+    it('calls api.deleteAccount', async () => {
+      await run(['accounts', 'delete', 'acct-1']);
+
+      expect(api.deleteAccount).toHaveBeenCalledWith('acct-1');
+      expect(printOutput).toHaveBeenCalledWith(
+        { success: true, id: 'acct-1' },
+        undefined,
+      );
+    });
+  });
+
+  describe('balance', () => {
+    it('calls api.getAccountBalance without cutoff', async () => {
+      await run(['accounts', 'balance', 'acct-1']);
+
+      expect(api.getAccountBalance).toHaveBeenCalledWith('acct-1', undefined);
+      expect(printOutput).toHaveBeenCalledWith(
+        { id: 'acct-1', balance: 10000 },
+        undefined,
+      );
+    });
+
+    it('calls api.getAccountBalance with cutoff date', async () => {
+      await run(['accounts', 'balance', 'acct-1', '--cutoff', '2025-01-15']);
+
+      expect(api.getAccountBalance).toHaveBeenCalledWith(
+        'acct-1',
+        new Date('2025-01-15'),
+      );
+    });
+  });
+});
--- a/packages/cli/src/commands/accounts.ts
+++ b/packages/cli/src/commands/accounts.ts
@@ -0,0 +1,124 @@
+import * as api from '@actual-app/api';
+import type { Command } from 'commander';
+
+import { withConnection } from '../connection';
+import { printOutput } from '../output';
+import { parseIntFlag } from '../utils';
+
+export function registerAccountsCommand(program: Command) {
+  const accounts = program.command('accounts').description('Manage accounts');
+
+  accounts
+    .command('list')
+    .description('List all accounts')
+    .action(async () => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const result = await api.getAccounts();
+        printOutput(result, opts.format);
+      });
+    });
+
+  accounts
+    .command('create')
+    .description('Create a new account')
+    .requiredOption('--name <name>', 'Account name')
+    .option('--offbudget', 'Create as off-budget account', false)
+    .option('--balance <amount>', 'Initial balance in cents', '0')
+    .action(async cmdOpts => {
+      const balance = parseIntFlag(cmdOpts.balance, '--balance');
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const id = await api.createAccount(
+          { name: cmdOpts.name, offbudget: cmdOpts.offbudget },
+          balance,
+        );
+        printOutput({ id }, opts.format);
+      });
+    });
+
+  accounts
+    .command('update <id>')
+    .description('Update an account')
+    .option('--name <name>', 'New account name')
+    .option('--offbudget <bool>', 'Set off-budget status')
+    .action(async (id: string, cmdOpts) => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const fields: Record<string, unknown> = {};
+        if (cmdOpts.name !== undefined) fields.name = cmdOpts.name;
+        if (cmdOpts.offbudget !== undefined) {
+          fields.offbudget = cmdOpts.offbudget === 'true';
+        }
+        await api.updateAccount(id, fields);
+        printOutput({ success: true, id }, opts.format);
+      });
+    });
+
+  accounts
+    .command('close <id>')
+    .description('Close an account')
+    .option(
+      '--transfer-account <id>',
+      'Transfer remaining balance to this account',
+    )
+    .option(
+      '--transfer-category <id>',
+      'Transfer remaining balance to this category',
+    )
+    .action(async (id: string, cmdOpts) => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        await api.closeAccount(
+          id,
+          cmdOpts.transferAccount,
+          cmdOpts.transferCategory,
+        );
+        printOutput({ success: true, id }, opts.format);
+      });
+    });
+
+  accounts
+    .command('reopen <id>')
+    .description('Reopen a closed account')
+    .action(async (id: string) => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        await api.reopenAccount(id);
+        printOutput({ success: true, id }, opts.format);
+      });
+    });
+
+  accounts
+    .command('delete <id>')
+    .description('Delete an account')
+    .action(async (id: string) => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        await api.deleteAccount(id);
+        printOutput({ success: true, id }, opts.format);
+      });
+    });
+
+  accounts
+    .command('balance <id>')
+    .description('Get account balance')
+    .option('--cutoff <date>', 'Cutoff date (YYYY-MM-DD)')
+    .action(async (id: string, cmdOpts) => {
+      let cutoff: Date | undefined;
+      if (cmdOpts.cutoff) {
+        const cutoffDate = new Date(cmdOpts.cutoff);
+        if (Number.isNaN(cutoffDate.getTime())) {
+          throw new Error(
+            'Invalid cutoff date: expected a valid date (e.g. YYYY-MM-DD).',
+          );
+        }
+        cutoff = cutoffDate;
+      }
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const balance = await api.getAccountBalance(id, cutoff);
+        printOutput({ id, balance }, opts.format);
+      });
+    });
+}
--- a/packages/cli/src/commands/budgets.ts
+++ b/packages/cli/src/commands/budgets.ts
@@ -0,0 +1,135 @@
+import * as api from '@actual-app/api';
+import type { Command } from 'commander';
+
+import { withConnection } from '../connection';
+import { printOutput } from '../output';
+import { parseIntFlag } from '../utils';
+
+export function registerBudgetsCommand(program: Command) {
+  const budgets = program.command('budgets').description('Manage budgets');
+
+  budgets
+    .command('list')
+    .description('List all available budgets')
+    .action(async () => {
+      const opts = program.opts();
+      await withConnection(
+        opts,
+        async () => {
+          const result = await api.getBudgets();
+          printOutput(result, opts.format);
+        },
+        { loadBudget: false },
+      );
+    });
+
+  budgets
+    .command('download <syncId>')
+    .description('Download a budget by sync ID')
+    .option('--encryption-password <password>', 'Encryption password')
+    .action(async (syncId: string, cmdOpts) => {
+      const opts = program.opts();
+      await withConnection(
+        opts,
+        async () => {
+          await api.downloadBudget(syncId, {
+            password: cmdOpts.encryptionPassword,
+          });
+          printOutput({ success: true, syncId }, opts.format);
+        },
+        { loadBudget: false },
+      );
+    });
+
+  budgets
+    .command('sync')
+    .description('Sync the current budget')
+    .action(async () => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        await api.sync();
+        printOutput({ success: true }, opts.format);
+      });
+    });
+
+  budgets
+    .command('months')
+    .description('List available budget months')
+    .action(async () => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const result = await api.getBudgetMonths();
+        printOutput(result, opts.format);
+      });
+    });
+
+  budgets
+    .command('month <month>')
+    .description('Get budget data for a specific month (YYYY-MM)')
+    .action(async (month: string) => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const result = await api.getBudgetMonth(month);
+        printOutput(result, opts.format);
+      });
+    });
+
+  budgets
+    .command('set-amount')
+    .description('Set budget amount for a category in a month')
+    .requiredOption('--month <month>', 'Budget month (YYYY-MM)')
+    .requiredOption('--category <id>', 'Category ID')
+    .requiredOption('--amount <amount>', 'Amount in cents')
+    .action(async cmdOpts => {
+      const amount = parseIntFlag(cmdOpts.amount, '--amount');
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        await api.setBudgetAmount(cmdOpts.month, cmdOpts.category, amount);
+        printOutput({ success: true }, opts.format);
+      });
+    });
+
+  budgets
+    .command('set-carryover')
+    .description('Enable/disable carryover for a category')
+    .requiredOption('--month <month>', 'Budget month (YYYY-MM)')
+    .requiredOption('--category <id>', 'Category ID')
+    .requiredOption('--flag <bool>', 'Enable (true) or disable (false)')
+    .action(async cmdOpts => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        await api.setBudgetCarryover(
+          cmdOpts.month,
+          cmdOpts.category,
+          cmdOpts.flag === 'true',
+        );
+        printOutput({ success: true }, opts.format);
+      });
+    });
+
+  budgets
+    .command('hold-next-month')
+    .description('Hold budget amount for next month')
+    .requiredOption('--month <month>', 'Budget month (YYYY-MM)')
+    .requiredOption('--amount <amount>', 'Amount in cents')
+    .action(async cmdOpts => {
+      const parsedAmount = parseIntFlag(cmdOpts.amount, '--amount');
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        await api.holdBudgetForNextMonth(cmdOpts.month, parsedAmount);
+        printOutput({ success: true }, opts.format);
+      });
+    });
+
+  budgets
+    .command('reset-hold')
+    .description('Reset budget hold for a month')
+    .requiredOption('--month <month>', 'Budget month (YYYY-MM)')
+    .action(async cmdOpts => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        await api.resetBudgetHold(cmdOpts.month);
+        printOutput({ success: true }, opts.format);
+      });
+    });
+}
--- a/packages/cli/src/commands/categories.ts
+++ b/packages/cli/src/commands/categories.ts
@@ -0,0 +1,71 @@
+import * as api from '@actual-app/api';
+import type { Command } from 'commander';
+
+import { withConnection } from '../connection';
+import { printOutput } from '../output';
+
+export function registerCategoriesCommand(program: Command) {
+  const categories = program
+    .command('categories')
+    .description('Manage categories');
+
+  categories
+    .command('list')
+    .description('List all categories')
+    .action(async () => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const result = await api.getCategories();
+        printOutput(result, opts.format);
+      });
+    });
+
+  categories
+    .command('create')
+    .description('Create a new category')
+    .requiredOption('--name <name>', 'Category name')
+    .requiredOption('--group-id <id>', 'Category group ID')
+    .option('--is-income', 'Mark as income category', false)
+    .action(async cmdOpts => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const id = await api.createCategory({
+          name: cmdOpts.name,
+          group_id: cmdOpts.groupId,
+          is_income: cmdOpts.isIncome,
+          hidden: false,
+        });
+        printOutput({ id }, opts.format);
+      });
+    });
+
+  categories
+    .command('update <id>')
+    .description('Update a category')
+    .option('--name <name>', 'New category name')
+    .option('--hidden <bool>', 'Set hidden status')
+    .action(async (id: string, cmdOpts) => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const fields: Record<string, unknown> = {};
+        if (cmdOpts.name !== undefined) fields.name = cmdOpts.name;
+        if (cmdOpts.hidden !== undefined) {
+          fields.hidden = cmdOpts.hidden === 'true';
+        }
+        await api.updateCategory(id, fields);
+        printOutput({ success: true, id }, opts.format);
+      });
+    });
+
+  categories
+    .command('delete <id>')
+    .description('Delete a category')
+    .option('--transfer-to <id>', 'Transfer transactions to this category')
+    .action(async (id: string, cmdOpts) => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        await api.deleteCategory(id, cmdOpts.transferTo);
+        printOutput({ success: true, id }, opts.format);
+      });
+    });
+}
--- a/packages/cli/src/commands/category-groups.ts
+++ b/packages/cli/src/commands/category-groups.ts
@@ -0,0 +1,69 @@
+import * as api from '@actual-app/api';
+import type { Command } from 'commander';
+
+import { withConnection } from '../connection';
+import { printOutput } from '../output';
+
+export function registerCategoryGroupsCommand(program: Command) {
+  const groups = program
+    .command('category-groups')
+    .description('Manage category groups');
+
+  groups
+    .command('list')
+    .description('List all category groups')
+    .action(async () => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const result = await api.getCategoryGroups();
+        printOutput(result, opts.format);
+      });
+    });
+
+  groups
+    .command('create')
+    .description('Create a new category group')
+    .requiredOption('--name <name>', 'Group name')
+    .option('--is-income', 'Mark as income group', false)
+    .action(async cmdOpts => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const id = await api.createCategoryGroup({
+          name: cmdOpts.name,
+          is_income: cmdOpts.isIncome,
+          hidden: false,
+        });
+        printOutput({ id }, opts.format);
+      });
+    });
+
+  groups
+    .command('update <id>')
+    .description('Update a category group')
+    .option('--name <name>', 'New group name')
+    .option('--hidden <bool>', 'Set hidden status')
+    .action(async (id: string, cmdOpts) => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const fields: Record<string, unknown> = {};
+        if (cmdOpts.name !== undefined) fields.name = cmdOpts.name;
+        if (cmdOpts.hidden !== undefined) {
+          fields.hidden = cmdOpts.hidden === 'true';
+        }
+        await api.updateCategoryGroup(id, fields);
+        printOutput({ success: true, id }, opts.format);
+      });
+    });
+
+  groups
+    .command('delete <id>')
+    .description('Delete a category group')
+    .option('--transfer-to <id>', 'Transfer categories to this category group')
+    .action(async (id: string, cmdOpts) => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        await api.deleteCategoryGroup(id, cmdOpts.transferTo);
+        printOutput({ success: true, id }, opts.format);
+      });
+    });
+}
--- a/packages/cli/src/commands/payees.ts
+++ b/packages/cli/src/commands/payees.ts
@@ -0,0 +1,90 @@
+import * as api from '@actual-app/api';
+import type { Command } from 'commander';
+
+import { withConnection } from '../connection';
+import { printOutput } from '../output';
+
+export function registerPayeesCommand(program: Command) {
+  const payees = program.command('payees').description('Manage payees');
+
+  payees
+    .command('list')
+    .description('List all payees')
+    .action(async () => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const result = await api.getPayees();
+        printOutput(result, opts.format);
+      });
+    });
+
+  payees
+    .command('common')
+    .description('List frequently used payees')
+    .action(async () => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const result = await api.getCommonPayees();
+        printOutput(result, opts.format);
+      });
+    });
+
+  payees
+    .command('create')
+    .description('Create a new payee')
+    .requiredOption('--name <name>', 'Payee name')
+    .action(async cmdOpts => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const id = await api.createPayee({ name: cmdOpts.name });
+        printOutput({ id }, opts.format);
+      });
+    });
+
+  payees
+    .command('update <id>')
+    .description('Update a payee')
+    .option('--name <name>', 'New payee name')
+    .action(async (id: string, cmdOpts) => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const fields: Record<string, unknown> = {};
+        if (cmdOpts.name) fields.name = cmdOpts.name;
+        if (Object.keys(fields).length === 0) {
+          throw new Error(
+            'No fields to update. Use --name to specify a new name.',
+          );
+        }
+        await api.updatePayee(id, fields);
+        printOutput({ success: true, id }, opts.format);
+      });
+    });
+
+  payees
+    .command('delete <id>')
+    .description('Delete a payee')
+    .action(async (id: string) => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        await api.deletePayee(id);
+        printOutput({ success: true, id }, opts.format);
+      });
+    });
+
+  payees
+    .command('merge')
+    .description('Merge payees into a target payee')
+    .requiredOption('--target <id>', 'Target payee ID')
+    .requiredOption('--ids <ids>', 'Comma-separated payee IDs to merge')
+    .action(async (cmdOpts: { target: string; ids: string }) => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const mergeIds = cmdOpts.ids
+          .split(',')
+          .map(id => id.trim())
+          .filter(id => id.length > 0);
+        await api.mergePayees(cmdOpts.target, mergeIds);
+        printOutput({ success: true }, opts.format);
+      });
+    });
+}
--- a/packages/cli/src/commands/query.ts
+++ b/packages/cli/src/commands/query.ts
@@ -0,0 +1,88 @@
+import * as api from '@actual-app/api';
+import type { Command } from 'commander';
+
+import { withConnection } from '../connection';
+import { readJsonInput } from '../input';
+import { printOutput } from '../output';
+import { parseIntFlag } from '../utils';
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function buildQueryFromFile(
+  parsed: Record<string, unknown>,
+  fallbackTable: string | undefined,
+) {
+  const table = typeof parsed.table === 'string' ? parsed.table : fallbackTable;
+  let queryObj = api.q(table || 'transactions');
+  if (Array.isArray(parsed.select)) queryObj = queryObj.select(parsed.select);
+  if (isRecord(parsed.filter)) queryObj = queryObj.filter(parsed.filter);
+  if (Array.isArray(parsed.orderBy)) {
+    queryObj = queryObj.orderBy(parsed.orderBy);
+  }
+  if (typeof parsed.limit === 'number') queryObj = queryObj.limit(parsed.limit);
+  return queryObj;
+}
+
+function buildQueryFromFlags(cmdOpts: Record<string, string | undefined>) {
+  if (!cmdOpts.table) {
+    throw new Error('--table is required (or use --file)');
+  }
+  let queryObj = api.q(cmdOpts.table);
+
+  if (cmdOpts.select) {
+    queryObj = queryObj.select(cmdOpts.select.split(','));
+  }
+
+  if (cmdOpts.filter) {
+    queryObj = queryObj.filter(JSON.parse(cmdOpts.filter));
+  }
+
+  if (cmdOpts.orderBy) {
+    queryObj = queryObj.orderBy(cmdOpts.orderBy.split(','));
+  }
+
+  if (cmdOpts.limit) {
+    queryObj = queryObj.limit(parseIntFlag(cmdOpts.limit, '--limit'));
+  }
+
+  return queryObj;
+}
+
+export function registerQueryCommand(program: Command) {
+  const query = program
+    .command('query')
+    .description('Run AQL (Actual Query Language) queries');
+
+  query
+    .command('run')
+    .description('Execute an AQL query')
+    .option(
+      '--table <table>',
+      'Table to query (transactions, accounts, categories, payees)',
+    )
+    .option('--select <fields>', 'Comma-separated fields to select')
+    .option('--filter <json>', 'Filter expression as JSON')
+    .option('--order-by <fields>', 'Comma-separated fields to order by')
+    .option('--limit <n>', 'Limit number of results')
+    .option(
+      '--file <path>',
+      'Read full query object from JSON file (use - for stdin)',
+    )
+    .action(async cmdOpts => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const parsed = cmdOpts.file ? readJsonInput(cmdOpts) : undefined;
+        if (parsed !== undefined && !isRecord(parsed)) {
+          throw new Error('Query file must contain a JSON object');
+        }
+        const queryObj = parsed
+          ? buildQueryFromFile(parsed, cmdOpts.table)
+          : buildQueryFromFlags(cmdOpts);
+
+        const result = await api.aqlQuery(queryObj);
+        printOutput(result, opts.format);
+      });
+    });
+}
--- a/packages/cli/src/commands/rules.ts
+++ b/packages/cli/src/commands/rules.ts
@@ -0,0 +1,77 @@
+import * as api from '@actual-app/api';
+import type { Command } from 'commander';
+
+import { withConnection } from '../connection';
+import { readJsonInput } from '../input';
+import { printOutput } from '../output';
+
+export function registerRulesCommand(program: Command) {
+  const rules = program
+    .command('rules')
+    .description('Manage transaction rules');
+
+  rules
+    .command('list')
+    .description('List all rules')
+    .action(async () => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const result = await api.getRules();
+        printOutput(result, opts.format);
+      });
+    });
+
+  rules
+    .command('payee-rules <payeeId>')
+    .description('List rules for a specific payee')
+    .action(async (payeeId: string) => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const result = await api.getPayeeRules(payeeId);
+        printOutput(result, opts.format);
+      });
+    });
+
+  rules
+    .command('create')
+    .description('Create a new rule')
+    .option('--data <json>', 'Rule definition as JSON')
+    .option('--file <path>', 'Read rule from JSON file (use - for stdin)')
+    .action(async cmdOpts => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const rule = readJsonInput(cmdOpts) as Parameters<
+          typeof api.createRule
+        >[0];
+        const id = await api.createRule(rule);
+        printOutput({ id }, opts.format);
+      });
+    });
+
+  rules
+    .command('update')
+    .description('Update a rule')
+    .option('--data <json>', 'Rule data as JSON (must include id)')
+    .option('--file <path>', 'Read rule from JSON file (use - for stdin)')
+    .action(async cmdOpts => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const rule = readJsonInput(cmdOpts) as Parameters<
+          typeof api.updateRule
+        >[0];
+        await api.updateRule(rule);
+        printOutput({ success: true }, opts.format);
+      });
+    });
+
+  rules
+    .command('delete <id>')
+    .description('Delete a rule')
+    .action(async (id: string) => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        await api.deleteRule(id);
+        printOutput({ success: true, id }, opts.format);
+      });
+    });
+}
--- a/packages/cli/src/commands/schedules.ts
+++ b/packages/cli/src/commands/schedules.ts
@@ -0,0 +1,67 @@
+import * as api from '@actual-app/api';
+import type { Command } from 'commander';
+
+import { withConnection } from '../connection';
+import { readJsonInput } from '../input';
+import { printOutput } from '../output';
+
+export function registerSchedulesCommand(program: Command) {
+  const schedules = program
+    .command('schedules')
+    .description('Manage scheduled transactions');
+
+  schedules
+    .command('list')
+    .description('List all schedules')
+    .action(async () => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const result = await api.getSchedules();
+        printOutput(result, opts.format);
+      });
+    });
+
+  schedules
+    .command('create')
+    .description('Create a new schedule')
+    .option('--data <json>', 'Schedule definition as JSON')
+    .option('--file <path>', 'Read schedule from JSON file (use - for stdin)')
+    .action(async cmdOpts => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const schedule = readJsonInput(cmdOpts) as Parameters<
+          typeof api.createSchedule
+        >[0];
+        const id = await api.createSchedule(schedule);
+        printOutput({ id }, opts.format);
+      });
+    });
+
+  schedules
+    .command('update <id>')
+    .description('Update a schedule')
+    .option('--data <json>', 'Fields to update as JSON')
+    .option('--file <path>', 'Read fields from JSON file (use - for stdin)')
+    .option('--reset-next-date', 'Reset next occurrence date', false)
+    .action(async (id: string, cmdOpts) => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const fields = readJsonInput(cmdOpts) as Parameters<
+          typeof api.updateSchedule
+        >[1];
+        await api.updateSchedule(id, fields, cmdOpts.resetNextDate);
+        printOutput({ success: true, id }, opts.format);
+      });
+    });
+
+  schedules
+    .command('delete <id>')
+    .description('Delete a schedule')
+    .action(async (id: string) => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        await api.deleteSchedule(id);
+        printOutput({ success: true, id }, opts.format);
+      });
+    });
+}
--- a/packages/cli/src/commands/server.ts
+++ b/packages/cli/src/commands/server.ts
@@ -0,0 +1,60 @@
+import * as api from '@actual-app/api';
+import { Option } from 'commander';
+import type { Command } from 'commander';
+
+import { withConnection } from '../connection';
+import { printOutput } from '../output';
+
+export function registerServerCommand(program: Command) {
+  const server = program.command('server').description('Server utilities');
+
+  server
+    .command('version')
+    .description('Get server version')
+    .action(async () => {
+      const opts = program.opts();
+      await withConnection(
+        opts,
+        async () => {
+          const version = await api.getServerVersion();
+          printOutput({ version }, opts.format);
+        },
+        { loadBudget: false },
+      );
+    });
+
+  server
+    .command('get-id')
+    .description('Get entity ID by name')
+    .addOption(
+      new Option('--type <type>', 'Entity type')
+        .choices(['accounts', 'categories', 'payees', 'schedules'])
+        .makeOptionMandatory(),
+    )
+    .requiredOption('--name <name>', 'Entity name')
+    .action(async cmdOpts => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const id = await api.getIDByName(cmdOpts.type, cmdOpts.name);
+        printOutput(
+          { id, type: cmdOpts.type, name: cmdOpts.name },
+          opts.format,
+        );
+      });
+    });
+
+  server
+    .command('bank-sync')
+    .description('Run bank synchronization')
+    .option('--account <id>', 'Specific account ID to sync')
+    .action(async cmdOpts => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const args = cmdOpts.account
+          ? { accountId: cmdOpts.account }
+          : undefined;
+        await api.runBankSync(args);
+        printOutput({ success: true }, opts.format);
+      });
+    });
+}
--- a/packages/cli/src/commands/tags.ts
+++ b/packages/cli/src/commands/tags.ts
@@ -0,0 +1,69 @@
+import * as api from '@actual-app/api';
+import type { Command } from 'commander';
+
+import { withConnection } from '../connection';
+import { printOutput } from '../output';
+
+export function registerTagsCommand(program: Command) {
+  const tags = program.command('tags').description('Manage tags');
+
+  tags
+    .command('list')
+    .description('List all tags')
+    .action(async () => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const result = await api.getTags();
+        printOutput(result, opts.format);
+      });
+    });
+
+  tags
+    .command('create')
+    .description('Create a new tag')
+    .requiredOption('--tag <tag>', 'Tag name')
+    .option('--color <color>', 'Tag color')
+    .option('--description <description>', 'Tag description')
+    .action(async cmdOpts => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const id = await api.createTag({
+          tag: cmdOpts.tag,
+          color: cmdOpts.color,
+          description: cmdOpts.description,
+        });
+        printOutput({ id }, opts.format);
+      });
+    });
+
+  tags
+    .command('update <id>')
+    .description('Update a tag')
+    .option('--tag <tag>', 'New tag name')
+    .option('--color <color>', 'New tag color')
+    .option('--description <description>', 'New tag description')
+    .action(async (id: string, cmdOpts) => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const fields: Record<string, unknown> = {};
+        if (cmdOpts.tag !== undefined) fields.tag = cmdOpts.tag;
+        if (cmdOpts.color !== undefined) fields.color = cmdOpts.color;
+        if (cmdOpts.description !== undefined) {
+          fields.description = cmdOpts.description;
+        }
+        await api.updateTag(id, fields);
+        printOutput({ success: true, id }, opts.format);
+      });
+    });
+
+  tags
+    .command('delete <id>')
+    .description('Delete a tag')
+    .action(async (id: string) => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        await api.deleteTag(id);
+        printOutput({ success: true, id }, opts.format);
+      });
+    });
+}
--- a/packages/cli/src/commands/transactions.ts
+++ b/packages/cli/src/commands/transactions.ts
@@ -0,0 +1,114 @@
+import * as api from '@actual-app/api';
+import type { Command } from 'commander';
+
+import { withConnection } from '../connection';
+import { readJsonInput } from '../input';
+import { printOutput } from '../output';
+
+export function registerTransactionsCommand(program: Command) {
+  const transactions = program
+    .command('transactions')
+    .description('Manage transactions');
+
+  transactions
+    .command('list')
+    .description('List transactions for an account')
+    .requiredOption('--account <id>', 'Account ID')
+    .requiredOption('--start <date>', 'Start date (YYYY-MM-DD)')
+    .requiredOption('--end <date>', 'End date (YYYY-MM-DD)')
+    .action(async cmdOpts => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const result = await api.getTransactions(
+          cmdOpts.account,
+          cmdOpts.start,
+          cmdOpts.end,
+        );
+        printOutput(result, opts.format);
+      });
+    });
+
+  transactions
+    .command('add')
+    .description('Add transactions to an account')
+    .requiredOption('--account <id>', 'Account ID')
+    .option('--data <json>', 'Transaction data as JSON array')
+    .option(
+      '--file <path>',
+      'Read transaction data from JSON file (use - for stdin)',
+    )
+    .option('--learn-categories', 'Learn category assignments', false)
+    .option('--run-transfers', 'Process transfers', false)
+    .action(async cmdOpts => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const transactions = readJsonInput(cmdOpts) as Parameters<
+          typeof api.addTransactions
+        >[1];
+        const result = await api.addTransactions(
+          cmdOpts.account,
+          transactions,
+          {
+            learnCategories: cmdOpts.learnCategories,
+            runTransfers: cmdOpts.runTransfers,
+          },
+        );
+        printOutput(result, opts.format);
+      });
+    });
+
+  transactions
+    .command('import')
+    .description('Import transactions to an account')
+    .requiredOption('--account <id>', 'Account ID')
+    .option('--data <json>', 'Transaction data as JSON array')
+    .option(
+      '--file <path>',
+      'Read transaction data from JSON file (use - for stdin)',
+    )
+    .option('--dry-run', 'Preview without importing', false)
+    .action(async cmdOpts => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const transactions = readJsonInput(cmdOpts) as Parameters<
+          typeof api.importTransactions
+        >[1];
+        const result = await api.importTransactions(
+          cmdOpts.account,
+          transactions,
+          {
+            defaultCleared: true,
+            dryRun: cmdOpts.dryRun,
+          },
+        );
+        printOutput(result, opts.format);
+      });
+    });
+
+  transactions
+    .command('update <id>')
+    .description('Update a transaction')
+    .option('--data <json>', 'Fields to update as JSON')
+    .option('--file <path>', 'Read fields from JSON file (use - for stdin)')
+    .action(async (id: string, cmdOpts) => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const fields = readJsonInput(cmdOpts) as Parameters<
+          typeof api.updateTransaction
+        >[1];
+        await api.updateTransaction(id, fields);
+        printOutput({ success: true, id }, opts.format);
+      });
+    });
+
+  transactions
+    .command('delete <id>')
+    .description('Delete a transaction')
+    .action(async (id: string) => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        await api.deleteTransaction(id);
+        printOutput({ success: true, id }, opts.format);
+      });
+    });
+}
--- a/packages/cli/src/config.test.ts
+++ b/packages/cli/src/config.test.ts
@@ -0,0 +1,177 @@
+import { homedir } from 'os';
+import { join } from 'path';
+
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { resolveConfig } from './config';
+
+const mockSearch = vi.fn().mockResolvedValue(null);
+
+vi.mock('cosmiconfig', () => ({
+  cosmiconfig: () => ({
+    search: (...args: unknown[]) => mockSearch(...args),
+  }),
+}));
+
+function mockConfigFile(config: Record<string, unknown> | null) {
+  if (config) {
+    mockSearch.mockResolvedValue({ config, isEmpty: false });
+  } else {
+    mockSearch.mockResolvedValue(null);
+  }
+}
+
+describe('resolveConfig', () => {
+  const savedEnv: Record<string, string | undefined> = {};
+  const envKeys = [
+    'ACTUAL_SERVER_URL',
+    'ACTUAL_PASSWORD',
+    'ACTUAL_SESSION_TOKEN',
+    'ACTUAL_BUDGET_ID',
+    'ACTUAL_DATA_DIR',
+  ];
+
+  beforeEach(() => {
+    for (const key of envKeys) {
+      savedEnv[key] = process.env[key];
+      delete process.env[key];
+    }
+    mockConfigFile(null);
+  });
+
+  afterEach(() => {
+    for (const key of envKeys) {
+      if (savedEnv[key] !== undefined) {
+        process.env[key] = savedEnv[key];
+      } else {
+        delete process.env[key];
+      }
+    }
+  });
+
+  describe('priority chain', () => {
+    it('CLI opts take highest priority', async () => {
+      process.env.ACTUAL_SERVER_URL = 'http://env';
+      process.env.ACTUAL_PASSWORD = 'envpw';
+      mockConfigFile({
+        serverUrl: 'http://file',
+        password: 'filepw',
+      });
+
+      const config = await resolveConfig({
+        serverUrl: 'http://cli',
+        password: 'clipw',
+      });
+
+      expect(config.serverUrl).toBe('http://cli');
+      expect(config.password).toBe('clipw');
+    });
+
+    it('env vars override file config', async () => {
+      process.env.ACTUAL_SERVER_URL = 'http://env';
+      process.env.ACTUAL_PASSWORD = 'envpw';
+      mockConfigFile({
+        serverUrl: 'http://file',
+        password: 'filepw',
+      });
+
+      const config = await resolveConfig({});
+
+      expect(config.serverUrl).toBe('http://env');
+      expect(config.password).toBe('envpw');
+    });
+
+    it('file config is used when no CLI opts or env vars', async () => {
+      mockConfigFile({
+        serverUrl: 'http://file',
+        password: 'filepw',
+        budgetId: 'budget-1',
+      });
+
+      const config = await resolveConfig({});
+
+      expect(config.serverUrl).toBe('http://file');
+      expect(config.password).toBe('filepw');
+      expect(config.budgetId).toBe('budget-1');
+    });
+  });
+
+  describe('defaults', () => {
+    it('dataDir defaults to ~/.actual-cli/data', async () => {
+      const config = await resolveConfig({
+        serverUrl: 'http://test',
+        password: 'pw',
+      });
+
+      expect(config.dataDir).toBe(join(homedir(), '.actual-cli', 'data'));
+    });
+
+    it('CLI opt overrides default dataDir', async () => {
+      const config = await resolveConfig({
+        serverUrl: 'http://test',
+        password: 'pw',
+        dataDir: '/custom/dir',
+      });
+
+      expect(config.dataDir).toBe('/custom/dir');
+    });
+  });
+
+  describe('validation', () => {
+    it('throws when serverUrl is missing', async () => {
+      await expect(resolveConfig({ password: 'pw' })).rejects.toThrow(
+        'Server URL is required',
+      );
+    });
+
+    it('throws when neither password nor sessionToken provided', async () => {
+      await expect(resolveConfig({ serverUrl: 'http://test' })).rejects.toThrow(
+        'Authentication required',
+      );
+    });
+
+    it('accepts sessionToken without password', async () => {
+      const config = await resolveConfig({
+        serverUrl: 'http://test',
+        sessionToken: 'tok',
+      });
+
+      expect(config.sessionToken).toBe('tok');
+      expect(config.password).toBeUndefined();
+    });
+
+    it('accepts password without sessionToken', async () => {
+      const config = await resolveConfig({
+        serverUrl: 'http://test',
+        password: 'pw',
+      });
+
+      expect(config.password).toBe('pw');
+      expect(config.sessionToken).toBeUndefined();
+    });
+  });
+
+  describe('cosmiconfig handling', () => {
+    it('handles null result (no config file found)', async () => {
+      mockConfigFile(null);
+
+      const config = await resolveConfig({
+        serverUrl: 'http://test',
+        password: 'pw',
+      });
+
+      expect(config.serverUrl).toBe('http://test');
+    });
+
+    it('handles isEmpty result', async () => {
+      mockSearch.mockResolvedValue({ config: {}, isEmpty: true });
+
+      const config = await resolveConfig({
+        serverUrl: 'http://test',
+        password: 'pw',
+      });
+
+      expect(config.serverUrl).toBe('http://test');
+    });
+  });
+});
--- a/packages/cli/src/config.ts
+++ b/packages/cli/src/config.ts
@@ -0,0 +1,97 @@
+import { homedir } from 'os';
+import { join } from 'path';
+
+import { cosmiconfig } from 'cosmiconfig';
+
+export type CliConfig = {
+  serverUrl: string;
+  password?: string;
+  sessionToken?: string;
+  budgetId?: string;
+  dataDir: string;
+  encryptionPassword?: string;
+};
+
+export type CliGlobalOpts = {
+  serverUrl?: string;
+  password?: string;
+  sessionToken?: string;
+  budgetId?: string;
+  dataDir?: string;
+  encryptionPassword?: string;
+  format?: 'json' | 'table' | 'csv';
+  quiet?: boolean;
+};
+
+type ConfigFileContent = {
+  serverUrl?: string;
+  password?: string;
+  sessionToken?: string;
+  budgetId?: string;
+  dataDir?: string;
+  encryptionPassword?: string;
+};
+
+async function loadConfigFile(): Promise<ConfigFileContent> {
+  const explorer = cosmiconfig('actual');
+  const result = await explorer.search();
+  if (result && !result.isEmpty) {
+    return result.config as ConfigFileContent;
+  }
+  return {};
+}
+
+export async function resolveConfig(
+  cliOpts: CliGlobalOpts,
+): Promise<CliConfig> {
+  const fileConfig = await loadConfigFile();
+
+  const serverUrl =
+    cliOpts.serverUrl ??
+    process.env.ACTUAL_SERVER_URL ??
+    fileConfig.serverUrl ??
+    '';
+
+  const password =
+    cliOpts.password ?? process.env.ACTUAL_PASSWORD ?? fileConfig.password;
+
+  const sessionToken =
+    cliOpts.sessionToken ??
+    process.env.ACTUAL_SESSION_TOKEN ??
+    fileConfig.sessionToken;
+
+  const budgetId =
+    cliOpts.budgetId ?? process.env.ACTUAL_BUDGET_ID ?? fileConfig.budgetId;
+
+  const dataDir =
+    cliOpts.dataDir ??
+    process.env.ACTUAL_DATA_DIR ??
+    fileConfig.dataDir ??
+    join(homedir(), '.actual-cli', 'data');
+
+  const encryptionPassword =
+    cliOpts.encryptionPassword ??
+    process.env.ACTUAL_ENCRYPTION_PASSWORD ??
+    fileConfig.encryptionPassword;
+
+  if (!serverUrl) {
+    throw new Error(
+      'Server URL is required. Set --server-url, ACTUAL_SERVER_URL env var, or serverUrl in config file.',
+    );
+  }
+
+  if (!password && !sessionToken) {
+    throw new Error(
+      'Authentication required. Set --password/--session-token, ACTUAL_PASSWORD/ACTUAL_SESSION_TOKEN env var, or password/sessionToken in config file.',
+    );
+  }
+
+  return {
+    serverUrl,
+    password,
+    sessionToken,
+    budgetId,
+    dataDir,
+    encryptionPassword,
+  };
+}
--- a/packages/cli/src/connection.test.ts
+++ b/packages/cli/src/connection.test.ts
@@ -0,0 +1,133 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('@actual-app/api', () => ({
+  init: vi.fn().mockResolvedValue(undefined),
+  downloadBudget: vi.fn().mockResolvedValue(undefined),
+  shutdown: vi.fn().mockResolvedValue(undefined),
+}));
+
+vi.mock('./config', () => ({
+  resolveConfig: vi.fn(),
+}));
+
+const api = await import('@actual-app/api');
+const { resolveConfig } = await import('./config');
+const { withConnection } = await import('./connection');
+
+function setConfig(overrides: Record<string, unknown> = {}) {
+  vi.mocked(resolveConfig).mockResolvedValue({
+    serverUrl: 'http://test',
+    password: 'pw',
+    dataDir: '/tmp/data',
+    budgetId: 'budget-1',
+    ...overrides,
+  });
+}
+
+describe('withConnection', () => {
+  let stderrSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    vi.clearAllMocks();
+    stderrSpy = vi
+      .spyOn(process.stderr, 'write')
+      .mockImplementation(() => true);
+    setConfig();
+  });
+
+  afterEach(() => {
+    stderrSpy.mockRestore();
+  });
+
+  it('calls api.init with password when no sessionToken', async () => {
+    setConfig({ password: 'pw', sessionToken: undefined });
+
+    await withConnection({}, async () => 'ok');
+
+    expect(api.init).toHaveBeenCalledWith({
+      serverUrl: 'http://test',
+      password: 'pw',
+      dataDir: '/tmp/data',
+    });
+  });
+
+  it('calls api.init with sessionToken when present', async () => {
+    setConfig({ sessionToken: 'tok', password: undefined });
+
+    await withConnection({}, async () => 'ok');
+
+    expect(api.init).toHaveBeenCalledWith({
+      serverUrl: 'http://test',
+      sessionToken: 'tok',
+      dataDir: '/tmp/data',
+    });
+  });
+
+  it('calls api.downloadBudget when budgetId is set', async () => {
+    setConfig({ budgetId: 'budget-1' });
+
+    await withConnection({}, async () => 'ok');
+
+    expect(api.downloadBudget).toHaveBeenCalledWith('budget-1', {
+      password: undefined,
+    });
+  });
+
+  it('throws when loadBudget is true but budgetId is not set', async () => {
+    setConfig({ budgetId: undefined });
+
+    await expect(withConnection({}, async () => 'ok')).rejects.toThrow(
+      'Budget ID is required',
+    );
+  });
+
+  it('skips budget download when loadBudget is false and budgetId is not set', async () => {
+    setConfig({ budgetId: undefined });
+
+    await withConnection({}, async () => 'ok', { loadBudget: false });
+
+    expect(api.downloadBudget).not.toHaveBeenCalled();
+  });
+
+  it('does not call api.downloadBudget when loadBudget is false', async () => {
+    setConfig({ budgetId: 'budget-1' });
+
+    await withConnection({}, async () => 'ok', { loadBudget: false });
+
+    expect(api.downloadBudget).not.toHaveBeenCalled();
+  });
+
+  it('returns callback result', async () => {
+    const result = await withConnection({}, async () => 42);
+    expect(result).toBe(42);
+  });
+
+  it('calls api.shutdown in finally block on success', async () => {
+    await withConnection({}, async () => 'ok');
+    expect(api.shutdown).toHaveBeenCalled();
+  });
+
+  it('calls api.shutdown in finally block on error', async () => {
+    await expect(
+      withConnection({}, async () => {
+        throw new Error('boom');
+      }),
+    ).rejects.toThrow('boom');
+
+    expect(api.shutdown).toHaveBeenCalled();
+  });
+
+  it('writes info to stderr when not quiet', async () => {
+    await withConnection({}, async () => 'ok');
+
+    expect(stderrSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Connecting to'),
+    );
+  });
+
+  it('does not write to stderr when quiet', async () => {
+    await withConnection({ quiet: true }, async () => 'ok');
+
+    expect(stderrSpy).not.toHaveBeenCalled();
+  });
+});
--- a/packages/cli/src/connection.ts
+++ b/packages/cli/src/connection.ts
@@ -0,0 +1,65 @@
+import { mkdirSync } from 'fs';
+
+import * as api from '@actual-app/api';
+
+import { resolveConfig } from './config';
+import type { CliGlobalOpts } from './config';
+
+function info(message: string, quiet?: boolean) {
+  if (!quiet) {
+    process.stderr.write(message + '\n');
+  }
+}
+
+type ConnectionOptions = {
+  loadBudget?: boolean;
+};
+
+export async function withConnection<T>(
+  globalOpts: CliGlobalOpts,
+  fn: () => Promise<T>,
+  options: ConnectionOptions = {},
+): Promise<T> {
+  const { loadBudget = true } = options;
+  const config = await resolveConfig(globalOpts);
+
+  mkdirSync(config.dataDir, { recursive: true });
+
+  info(`Connecting to ${config.serverUrl}...`, globalOpts.quiet);
+
+  if (config.sessionToken) {
+    await api.init({
+      serverURL: config.serverUrl,
+      dataDir: config.dataDir,
+      sessionToken: config.sessionToken,
+      verbose: !globalOpts.quiet,
+    });
+  } else if (config.password) {
+    await api.init({
+      serverURL: config.serverUrl,
+      dataDir: config.dataDir,
+      password: config.password,
+      verbose: !globalOpts.quiet,
+    });
+  } else {
+    throw new Error(
+      'Authentication required. Provide --password or --session-token, or set ACTUAL_PASSWORD / ACTUAL_SESSION_TOKEN.',
+    );
+  }
+
+  try {
+    if (loadBudget && config.budgetId) {
+      info(`Downloading budget ${config.budgetId}...`, globalOpts.quiet);
+      await api.downloadBudget(config.budgetId, {
+        password: config.encryptionPassword,
+      });
+    } else if (loadBudget && !config.budgetId) {
+      throw new Error(
+        'Budget ID is required for this command. Set --budget-id or ACTUAL_BUDGET_ID.',
+      );
+    }
+    return await fn();
+  } finally {
+    await api.shutdown();
+  }
+}
--- a/packages/cli/src/index.ts
+++ b/packages/cli/src/index.ts
@@ -0,0 +1,64 @@
+import { Command, Option } from 'commander';
+
+import { registerAccountsCommand } from './commands/accounts';
+import { registerBudgetsCommand } from './commands/budgets';
+import { registerCategoriesCommand } from './commands/categories';
+import { registerCategoryGroupsCommand } from './commands/category-groups';
+import { registerPayeesCommand } from './commands/payees';
+import { registerQueryCommand } from './commands/query';
+import { registerRulesCommand } from './commands/rules';
+import { registerSchedulesCommand } from './commands/schedules';
+import { registerServerCommand } from './commands/server';
+import { registerTagsCommand } from './commands/tags';
+import { registerTransactionsCommand } from './commands/transactions';
+
+declare const __CLI_VERSION__: string;
+
+const program = new Command();
+
+program
+  .name('actual')
+  .description('CLI for Actual Budget')
+  .version(__CLI_VERSION__)
+  .option('--server-url <url>', 'Actual server URL (env: ACTUAL_SERVER_URL)')
+  .option('--password <password>', 'Server password (env: ACTUAL_PASSWORD)')
+  .option(
+    '--session-token <token>',
+    'Session token (env: ACTUAL_SESSION_TOKEN)',
+  )
+  .option('--budget-id <id>', 'Budget ID to load (env: ACTUAL_BUDGET_ID)')
+  .option('--data-dir <path>', 'Data directory (env: ACTUAL_DATA_DIR)')
+  .option(
+    '--encryption-password <password>',
+    'E2E encryption password (env: ACTUAL_ENCRYPTION_PASSWORD)',
+  )
+  .addOption(
+    new Option('--format <format>', 'Output format: json, table, csv')
+      .choices(['json', 'table', 'csv'] as const)
+      .default('json'),
+  )
+  .option('--quiet', 'Suppress informational messages', false);
+
+registerAccountsCommand(program);
+registerBudgetsCommand(program);
+registerCategoriesCommand(program);
+registerCategoryGroupsCommand(program);
+registerTransactionsCommand(program);
+registerPayeesCommand(program);
+registerTagsCommand(program);
+registerRulesCommand(program);
+registerSchedulesCommand(program);
+registerQueryCommand(program);
+registerServerCommand(program);
+
+function normalizeThrownMessage(err: unknown): string {
+  if (err instanceof Error) return err.message;
+  if (typeof err === 'object' && err !== null) return JSON.stringify(err);
+  return String(err);
+}
+
+program.parseAsync(process.argv).catch((err: unknown) => {
+  const message = normalizeThrownMessage(err);
+  process.stderr.write(`Error: ${message}\n`);
+  process.exitCode = 1;
+});
--- a/packages/cli/src/input.ts
+++ b/packages/cli/src/input.ts
@@ -0,0 +1,18 @@
+import { readFileSync } from 'fs';
+
+export function readJsonInput(cmdOpts: {
+  data?: string;
+  file?: string;
+}): unknown {
+  if (cmdOpts.data) {
+    return JSON.parse(cmdOpts.data);
+  }
+  if (cmdOpts.file) {
+    const content =
+      cmdOpts.file === '-'
+        ? readFileSync(0, 'utf-8')
+        : readFileSync(cmdOpts.file, 'utf-8');
+    return JSON.parse(content);
+  }
+  throw new Error('Either --data or --file is required');
+}
--- a/packages/cli/src/output.test.ts
+++ b/packages/cli/src/output.test.ts
@@ -0,0 +1,154 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+import { formatOutput, printOutput } from './output';
+
+describe('formatOutput', () => {
+  describe('json (default)', () => {
+    it('pretty-prints with 2-space indent', () => {
+      const data = { a: 1, b: 'two' };
+      expect(formatOutput(data)).toBe(JSON.stringify(data, null, 2));
+    });
+
+    it('is the default format', () => {
+      expect(formatOutput({ x: 1 })).toBe(formatOutput({ x: 1 }, 'json'));
+    });
+
+    it('handles arrays', () => {
+      const data = [1, 2, 3];
+      expect(formatOutput(data, 'json')).toBe('[\n  1,\n  2,\n  3\n]');
+    });
+
+    it('handles null', () => {
+      expect(formatOutput(null, 'json')).toBe('null');
+    });
+  });
+
+  describe('table', () => {
+    it('renders an object as key-value table', () => {
+      const result = formatOutput({ name: 'Alice', age: 30 }, 'table');
+      expect(result).toContain('name');
+      expect(result).toContain('Alice');
+      expect(result).toContain('age');
+      expect(result).toContain('30');
+    });
+
+    it('renders an array of objects as columnar table', () => {
+      const data = [
+        { id: 1, name: 'a' },
+        { id: 2, name: 'b' },
+      ];
+      const result = formatOutput(data, 'table');
+      expect(result).toContain('id');
+      expect(result).toContain('name');
+      expect(result).toContain('1');
+      expect(result).toContain('a');
+      expect(result).toContain('2');
+      expect(result).toContain('b');
+    });
+
+    it('returns "(no results)" for empty array', () => {
+      expect(formatOutput([], 'table')).toBe('(no results)');
+    });
+
+    it('returns String(data) for scalar values', () => {
+      expect(formatOutput(42, 'table')).toBe('42');
+      expect(formatOutput('hello', 'table')).toBe('hello');
+      expect(formatOutput(true, 'table')).toBe('true');
+    });
+
+    it('handles null/undefined values in objects', () => {
+      const data = [{ a: null, b: undefined }];
+      const result = formatOutput(data, 'table');
+      expect(result).toContain('a');
+      expect(result).toContain('b');
+    });
+  });
+
+  describe('csv', () => {
+    it('renders array of objects as header + data rows', () => {
+      const data = [
+        { id: 1, name: 'Alice' },
+        { id: 2, name: 'Bob' },
+      ];
+      const result = formatOutput(data, 'csv');
+      const lines = result.split('\n');
+      expect(lines[0]).toBe('id,name');
+      expect(lines[1]).toBe('1,Alice');
+      expect(lines[2]).toBe('2,Bob');
+    });
+
+    it('renders single object as header + single row', () => {
+      const result = formatOutput({ x: 10, y: 20 }, 'csv');
+      const lines = result.split('\n');
+      expect(lines[0]).toBe('x,y');
+      expect(lines[1]).toBe('10,20');
+    });
+
+    it('returns empty string for empty array', () => {
+      expect(formatOutput([], 'csv')).toBe('');
+    });
+
+    it('returns String(data) for scalar values', () => {
+      expect(formatOutput(42, 'csv')).toBe('42');
+      expect(formatOutput('hello', 'csv')).toBe('hello');
+    });
+
+    it('escapes commas by quoting', () => {
+      const data = [{ val: 'a,b' }];
+      expect(formatOutput(data, 'csv')).toBe('val\n"a,b"');
+    });
+
+    it('escapes double quotes by doubling them', () => {
+      const data = [{ val: 'say "hi"' }];
+      expect(formatOutput(data, 'csv')).toBe('val\n"say ""hi"""');
+    });
+
+    it('escapes newlines by quoting', () => {
+      const data = [{ val: 'line1\nline2' }];
+      expect(formatOutput(data, 'csv')).toBe('val\n"line1\nline2"');
+    });
+
+    it('handles null/undefined values', () => {
+      const data = [{ a: null, b: undefined }];
+      const result = formatOutput(data, 'csv');
+      const lines = result.split('\n');
+      expect(lines[0]).toBe('a,b');
+    });
+  });
+});
+
+describe('printOutput', () => {
+  let writeSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    writeSpy = vi.spyOn(process.stdout, 'write').mockImplementation(() => true);
+  });
+
+  afterEach(() => {
+    writeSpy.mockRestore();
+  });
+
+  it('writes formatted output followed by newline', () => {
+    printOutput({ a: 1 }, 'json');
+    expect(writeSpy).toHaveBeenCalledWith(
+      JSON.stringify({ a: 1 }, null, 2) + '\n',
+    );
+  });
+
+  it('defaults to json format', () => {
+    printOutput([1, 2]);
+    expect(writeSpy).toHaveBeenCalledWith(
+      JSON.stringify([1, 2], null, 2) + '\n',
+    );
+  });
+
+  it('supports table format', () => {
+    printOutput([], 'table');
+    expect(writeSpy).toHaveBeenCalledWith('(no results)\n');
+  });
+
+  it('supports csv format', () => {
+    printOutput([], 'csv');
+    expect(writeSpy).toHaveBeenCalledWith('\n');
+  });
+});
--- a/packages/cli/src/output.ts
+++ b/packages/cli/src/output.ts
@@ -0,0 +1,82 @@
+import Table from 'cli-table3';
+
+export type OutputFormat = 'json' | 'table' | 'csv';
+
+export function formatOutput(
+  data: unknown,
+  format: OutputFormat = 'json',
+): string {
+  switch (format) {
+    case 'json':
+      return JSON.stringify(data, null, 2);
+    case 'table':
+      return formatTable(data);
+    case 'csv':
+      return formatCsv(data);
+    default:
+      return JSON.stringify(data, null, 2);
+  }
+}
+
+function formatTable(data: unknown): string {
+  if (!Array.isArray(data)) {
+    if (data && typeof data === 'object') {
+      const table = new Table();
+      for (const [key, value] of Object.entries(data)) {
+        table.push({ [key]: String(value) });
+      }
+      return table.toString();
+    }
+    return String(data);
+  }
+
+  if (data.length === 0) {
+    return '(no results)';
+  }
+
+  const keys = Object.keys(data[0] as Record<string, unknown>);
+  const table = new Table({ head: keys });
+
+  for (const row of data) {
+    const r = row as Record<string, unknown>;
+    table.push(keys.map(k => String(r[k] ?? '')));
+  }
+
+  return table.toString();
+}
+
+function formatCsv(data: unknown): string {
+  if (!Array.isArray(data)) {
+    if (data && typeof data === 'object') {
+      const entries = Object.entries(data);
+      const header = entries.map(([k]) => escapeCsv(k)).join(',');
+      const values = entries.map(([, v]) => escapeCsv(String(v))).join(',');
+      return header + '\n' + values;
+    }
+    return String(data);
+  }
+
+  if (data.length === 0) {
+    return '';
+  }
+
+  const keys = Object.keys(data[0] as Record<string, unknown>);
+  const header = keys.map(k => escapeCsv(k)).join(',');
+  const rows = data.map(row => {
+    const r = row as Record<string, unknown>;
+    return keys.map(k => escapeCsv(String(r[k] ?? ''))).join(',');
+  });
+
+  return [header, ...rows].join('\n');
+}
+
+function escapeCsv(value: string): string {
+  if (value.includes(',') || value.includes('"') || value.includes('\n')) {
+    return '"' + value.replace(/"/g, '""') + '"';
+  }
+  return value;
+}
+
+export function printOutput(data: unknown, format: OutputFormat = 'json') {
+  process.stdout.write(formatOutput(data, format) + '\n');
+}
--- a/packages/cli/src/utils.ts
+++ b/packages/cli/src/utils.ts
@@ -0,0 +1,7 @@
+export function parseIntFlag(value: string, flagName: string): number {
+  const parsed = parseInt(value, 10);
+  if (Number.isNaN(parsed)) {
+    throw new Error(`Invalid ${flagName}: "${value}". Expected an integer.`);
+  }
+  return parsed;
+}
--- a/packages/cli/tsconfig.json
+++ b/packages/cli/tsconfig.json
@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "composite": true,
+    "lib": ["ES2021"],
+    "types": ["node"],
+    "noEmit": false,
+    "strict": true,
+    "outDir": "dist",
+    "tsBuildInfoFile": "dist/.tsbuildinfo"
+  },
+  "references": [{ "path": "../api" }],
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "coverage"]
+}
--- a/packages/cli/vite.config.ts
+++ b/packages/cli/vite.config.ts
@@ -0,0 +1,31 @@
+import fs from 'fs';
+import path from 'path';
+
+import { defineConfig } from 'vite';
+
+const pkg = JSON.parse(
+  fs.readFileSync(path.resolve(__dirname, 'package.json'), 'utf-8'),
+);
+
+export default defineConfig({
+  define: {
+    __CLI_VERSION__: JSON.stringify(pkg.version),
+  },
+  ssr: { noExternal: true, external: ['@actual-app/api'] },
+  build: {
+    ssr: true,
+    target: 'node22',
+    outDir: path.resolve(__dirname, 'dist'),
+    emptyOutDir: true,
+    lib: {
+      entry: path.resolve(__dirname, 'src/index.ts'),
+      formats: ['es'],
+    },
+    rollupOptions: {
+      output: {
+        entryFileNames: 'cli.js',
+        banner: chunk => (chunk.isEntry ? '#!/usr/bin/env node' : ''),
+      },
+    },
+  },
+});
--- a/packages/cli/vitest.config.ts
+++ b/packages/cli/vitest.config.ts
@@ -0,0 +1,7 @@
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    globals: true,
+  },
+});
--- a/packages/docs/docs-sidebar.js
+++ b/packages/docs/docs-sidebar.js
@@ -230,6 +230,7 @@ const sidebars = {
          link: { type: 'doc', id: 'api/index' },
          items: [
            'api/reference',
+            'api/cli',
            {
              type: 'category',
              label: 'ActualQL',
--- a/packages/docs/docs/api/cli.md
+++ b/packages/docs/docs/api/cli.md
@@ -0,0 +1,356 @@
+---
+title: 'CLI'
+---
+
+# CLI Tool
+
+:::danger Experimental — API may change
+The CLI is **experimental** and its commands, options, and behavior are **likely to change** in future releases. Use it for scripting and automation with the understanding that updates may require changes to your workflows.
+:::
+
+The `@actual-app/cli` package provides a command-line interface for interacting with your Actual Budget data. It connects to your sync server and lets you query and modify budgets, accounts, transactions, categories, payees, rules, schedules, and more — all from the terminal.
+
+:::note
+This is different from the [sync-server CLI tool](../install/cli-tool.md) (`@actual-app/sync-server`), which is used to host and manage the Actual server itself.
+:::
+
+## Installation
+
+Node.js v22 or higher is required.
+
+```bash
+npm install --save @actual-app/cli
+```
+
+Or install globally:
+
+```bash
+npm install --location=global @actual-app/cli
+```
+
+## Configuration
+
+The CLI requires a connection to a running Actual sync server. Configuration can be provided via environment variables, CLI flags, or a config file.
+
+### Environment Variables
+
+| Variable               | Description                                         |
+| ---------------------- | --------------------------------------------------- |
+| `ACTUAL_SERVER_URL`    | URL of the Actual sync server (required)            |
+| `ACTUAL_BUDGET_ID`     | Budget ID to load (required for most commands)      |
+| `ACTUAL_PASSWORD`      | Server password (one of password or token required) |
+| `ACTUAL_SESSION_TOKEN` | Session token (alternative to password)             |
+
+### CLI Flags
+
+Global flags override environment variables:
+
+| Flag                      | Description                                     |
+| ------------------------- | ----------------------------------------------- |
+| `--server-url <url>`      | Server URL                                      |
+| `--password <pw>`         | Server password                                 |
+| `--session-token <token>` | Session token                                   |
+| `--budget-id <id>`        | Budget ID                                       |
+| `--data-dir <path>`       | Local data directory for cached budget data     |
+| `--format <format>`       | Output format: `json` (default), `table`, `csv` |
+| `--quiet`                 | Suppress informational messages on stderr       |
+
+### Config File
+
+The CLI uses [cosmiconfig](https://github.com/cosmiconfig/cosmiconfig) for configuration. You can create a config file in any of these formats:
+
+- `.actualrc` (JSON or YAML)
+- `.actualrc.json`, `.actualrc.yaml`, `.actualrc.yml`, `.actualrc.js`, `.actualrc.cjs`
+- `actual.config.js`, `actual.config.cjs`
+- An `"actual"` key in your `package.json`
+
+Example `.actualrc.json`:
+
+```json
+{
+  "serverUrl": "http://localhost:5006",
+  "password": "your-password",
+  "budgetId": "1cfdbb80-6274-49bf-b0c2-737235a4c81f"
+}
+```
+
+:::caution Security
+Avoid storing plaintext passwords in config files (including the `password` key above). Prefer environment variables such as `ACTUAL_PASSWORD` or `ACTUAL_SESSION_TOKEN`, or use a session token in config instead of a password.
+:::
+
+## Usage
+
+```bash
+actual <command> <subcommand> [options]
+```
+
+## Commands
+
+### Accounts
+
+```bash
+# List all accounts
+actual accounts list
+
+# Create an account
+actual accounts create --name "Checking" [--offbudget] [--balance 50000]
+
+# Update an account
+actual accounts update <id> [--name "New Name"] [--offbudget true]
+
+# Close an account (with optional transfer)
+actual accounts close <id> [--transfer-account <id>] [--transfer-category <id>]
+
+# Reopen a closed account
+actual accounts reopen <id>
+
+# Delete an account
+actual accounts delete <id>
+
+# Get account balance
+actual accounts balance <id> [--cutoff 2026-01-31]
+```
+
+### Budgets
+
+```bash
+# List available budgets on the server
+actual budgets list
+
+# Download a budget by sync ID
+actual budgets download <syncId> [--encryption-password <pw>]
+
+# Sync the current budget
+actual budgets sync
+
+# List budget months
+actual budgets months
+
+# View a specific month
+actual budgets month 2026-03
+
+# Set a budget amount (in integer cents)
+actual budgets set-amount --month 2026-03 --category <id> --amount 50000
+
+# Set carryover flag
+actual budgets set-carryover --month 2026-03 --category <id> --flag true
+
+# Hold funds for next month
+actual budgets hold-next-month --month 2026-03 --amount 10000
+
+# Reset held funds
+actual budgets reset-hold --month 2026-03
+```
+
+### Categories
+
+```bash
+# List all categories
+actual categories list
+
+# Create a category
+actual categories create --name "Groceries" --group-id <id> [--is-income]
+
+# Update a category
+actual categories update <id> [--name "Food"] [--hidden true]
+
+# Delete a category (with optional transfer)
+actual categories delete <id> [--transfer-to <id>]
+```
+
+### Category Groups
+
+```bash
+# List all category groups
+actual category-groups list
+
+# Create a category group
+actual category-groups create --name "Essentials" [--is-income]
+
+# Update a category group
+actual category-groups update <id> [--name "New Name"] [--hidden true]
+
+# Delete a category group (with optional transfer)
+actual category-groups delete <id> [--transfer-to <id>]
+```
+
+### Transactions
+
+```bash
+# List transactions for an account within a date range
+actual transactions list --account <id> --start 2026-01-01 --end 2026-03-31
+
+# Add transactions (inline JSON)
+actual transactions add --account <id> --data '[{"date":"2026-03-13","amount":-5000,"payee_name":"Store"}]'
+
+# Add transactions (from file)
+actual transactions add --account <id> --file transactions.json
+
+# Import transactions with reconciliation (deduplication)
+actual transactions import --account <id> --data '[...]' [--dry-run]
+
+# Update a transaction
+actual transactions update <id> --data '{"notes":"Updated note"}'
+
+# Delete a transaction
+actual transactions delete <id>
+```
+
+### Payees
+
+```bash
+# List all payees
+actual payees list
+
+# List common payees
+actual payees common
+
+# Create a payee
+actual payees create --name "Grocery Store"
+
+# Update a payee
+actual payees update <id> --name "New Name"
+
+# Delete a payee
+actual payees delete <id>
+
+# Merge multiple payees into one
+actual payees merge --target <id> --ids id1,id2,id3
+```
+
+### Tags
+
+```bash
+# List all tags
+actual tags list
+
+# Create a tag
+actual tags create --tag "vacation" [--color "#ff0000"] [--description "Vacation expenses"]
+
+# Update a tag
+actual tags update <id> [--tag "trip"] [--color "#00ff00"]
+
+# Delete a tag
+actual tags delete <id>
+```
+
+### Rules
+
+```bash
+# List all rules
+actual rules list
+
+# List rules for a specific payee
+actual rules payee-rules <payeeId>
+
+# Create a rule (inline JSON)
+actual rules create --data '{"stage":"pre","conditionsOp":"and","conditions":[...],"actions":[...]}'
+
+# Create a rule (from file)
+actual rules create --file rule.json
+
+# Update a rule
+actual rules update --data '{"id":"...","stage":"pre",...}'
+
+# Delete a rule
+actual rules delete <id>
+```
+
+### Schedules
+
+```bash
+# List all schedules
+actual schedules list
+
+# Create a schedule
+actual schedules create --data '{"name":"Rent","date":"1st","amount":-150000,"amountOp":"is","account":"...","payee":"..."}'
+
+# Update a schedule
+actual schedules update <id> --data '{"name":"Updated Rent"}' [--reset-next-date]
+
+# Delete a schedule
+actual schedules delete <id>
+```
+
+### Query (ActualQL)
+
+Run queries using [ActualQL](./actual-ql/index.md):
+
+```bash
+# Run a query (inline)
+actual query run --table transactions --select "date,amount,payee" --filter '{"amount":{"$lt":0}}' --limit 10
+
+# Run a query (from file)
+actual query run --file query.json
+```
+
+### Server
+
+```bash
+# Get the server version
+actual server version
+
+# Look up an entity ID by name
+actual server get-id --type accounts --name "Checking"
+actual server get-id --type categories --name "Groceries"
+
+# Trigger bank sync
+actual server bank-sync [--account <id>]
+```
+
+## Amount Convention
+
+All monetary amounts are represented as **integer cents**:
+
+| CLI Value | Dollar Amount |
+| --------- | ------------- |
+| `5000`    | $50.00        |
+| `-12350`  | -$123.50      |
+| `100`     | $1.00         |
+
+When providing amounts, always use integer cents. For example, to budget $50, pass `5000`.
+
+## Output Formats
+
+The `--format` flag controls how results are displayed:
+
+- **`json`** (default) — Machine-readable JSON output, ideal for scripting
+- **`table`** — Human-readable table format
+- **`csv`** — Comma-separated values for spreadsheet import
+
+Use `--quiet` to suppress informational messages on stderr when piping output to other tools.
+
+## Common Workflows
+
+**View your budget for the current month:**
+
+```bash
+actual budgets month 2026-03 --format table
+```
+
+**Check an account balance:**
+
+```bash
+# Find the account ID
+actual server get-id --type accounts --name "Checking" --quiet
+# Get the balance
+actual accounts balance <id> --quiet
+```
+
+**Export transactions to CSV:**
+
+```bash
+actual transactions list --account <id> --start 2026-01-01 --end 2026-12-31 --format csv > transactions.csv
+```
+
+**Add a transaction:**
+
+```bash
+actual transactions add --account <id> --data '[{"date":"2026-03-14","amount":-2500,"payee_name":"Coffee Shop"}]'
+```
+
+## Error Handling
+
+- Non-zero exit codes indicate an error
+- Error output is JSON on stdout: `{"error": "message"}`
+- Use `--quiet` to suppress informational stderr messages without affecting error output
--- a/packages/docs/docs/contributing/development-setup.md
+++ b/packages/docs/docs/contributing/development-setup.md
@@ -99,6 +99,9 @@ yarn build:desktop
 # Build API package
 yarn build:api

+# Build CLI package
+yarn build:cli
+
 # Build sync server
 yarn build:server
 ```
@@ -160,6 +163,9 @@ yarn build:desktop
 # API build
 yarn build:api

+# CLI build
+yarn build:cli
+
 # Sync server build
 yarn build:server
 ```
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -7,7 +7,8 @@
    { "path": "./packages/api" },
    { "path": "./packages/desktop-client" },
    { "path": "./packages/sync-server" },
-    { "path": "./packages/desktop-electron" }
+    { "path": "./packages/desktop-electron" },
+    { "path": "./packages/cli" }
  ],
  "compilerOptions": {
    "target": "ES2022",
--- a/upcoming-release-notes/7208.md
+++ b/upcoming-release-notes/7208.md
@@ -0,0 +1,6 @@
+---
+category: Features
+authors: [MatissJanis]
+---
+
+Actual-cli: tool for accessing your budget via the command line. Useful for AI agents
--- a/yarn.lock
+++ b/yarn.lock
@@ -19,7 +19,7 @@ __metadata:
  languageName: node
  linkType: hard

-"@actual-app/api@workspace:packages/api":
+"@actual-app/api@workspace:*, @actual-app/api@workspace:packages/api":
  version: 0.0.0-use.local
  resolution: "@actual-app/api@workspace:packages/api"
  dependencies:
@@ -49,6 +49,24 @@ __metadata:
  languageName: unknown
  linkType: soft

+"@actual-app/cli@workspace:packages/cli":
+  version: 0.0.0-use.local
+  resolution: "@actual-app/cli@workspace:packages/cli"
+  dependencies:
+    "@actual-app/api": "workspace:*"
+    "@types/node": "npm:^22.19.10"
+    "@typescript/native-preview": "npm:^7.0.0-dev.20260309.1"
+    cli-table3: "npm:^0.6.5"
+    commander: "npm:^13.0.0"
+    cosmiconfig: "npm:^9.0.0"
+    vite: "npm:^7.3.1"
+    vitest: "npm:^4.0.18"
+  bin:
+    actual: ./dist/cli.js
+    actual-cli: ./dist/cli.js
+  languageName: unknown
+  linkType: soft
+
 "@actual-app/components@workspace:*, @actual-app/components@workspace:packages/component-library":
  version: 0.0.0-use.local
  resolution: "@actual-app/components@workspace:packages/component-library"
@@ -13265,7 +13283,7 @@ __metadata:
  languageName: node
  linkType: hard

-"cli-table3@npm:^0.6.3":
+"cli-table3@npm:^0.6.3, cli-table3@npm:^0.6.5":
  version: 0.6.5
  resolution: "cli-table3@npm:0.6.5"
  dependencies:
@@ -13575,6 +13593,13 @@ __metadata:
  languageName: node
  linkType: hard

+"commander@npm:^13.0.0":
+  version: 13.1.0
+  resolution: "commander@npm:13.1.0"
+  checksum: 10/d3b4b79e6be8471ddadacbb8cd441fe82154d7da7393b50e76165a9e29ccdb74fa911a186437b9a211d0fc071db6051915c94fb8ef16d77511d898e9dbabc6af
+  languageName: node
+  linkType: hard
+
 "commander@npm:^14.0.0, commander@npm:^14.0.2":
  version: 14.0.2
  resolution: "commander@npm:14.0.2"
@@ -13975,6 +14000,23 @@ __metadata:
  languageName: node
  linkType: hard

+"cosmiconfig@npm:^9.0.0":
+  version: 9.0.1
+  resolution: "cosmiconfig@npm:9.0.1"
+  dependencies:
+    env-paths: "npm:^2.2.1"
+    import-fresh: "npm:^3.3.0"
+    js-yaml: "npm:^4.1.0"
+    parse-json: "npm:^5.2.0"
+  peerDependencies:
+    typescript: ">=4.9.5"
+  peerDependenciesMeta:
+    typescript:
+      optional: true
+  checksum: 10/89fcac84d062f0710091bb2d6a6175bcde22f5448877db9c43429694408191d3d4e215193b3ac4d54f7f89ef188d55cd481c7a2295b0dc572e65b528bf6fec01
+  languageName: node
+  linkType: hard
+
 "crc@npm:^3.8.0":
  version: 3.8.0
  resolution: "crc@npm:3.8.0"
@@ -15761,7 +15803,7 @@ __metadata:
  languageName: node
  linkType: hard

-"env-paths@npm:^2.2.0":
+"env-paths@npm:^2.2.0, env-paths@npm:^2.2.1":
  version: 2.2.1
  resolution: "env-paths@npm:2.2.1"
  checksum: 10/65b5df55a8bab92229ab2b40dad3b387fad24613263d103a97f91c9fe43ceb21965cd3392b1ccb5d77088021e525c4e0481adb309625d0cb94ade1d1fb8dc17e