[AI] Add #app-enablebanking subpath imports to sync-server package.json

Register enablebanking service, utils, and root entries in both
the imports and publishConfig.imports maps.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.claude/settings.json

@@ -0,0 +1,17 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Bash",
+        "hooks": [
+          {
+            "type": "command",
+            "if": "Bash(gh pr create*)",
+            "command": "echo '{\"hookSpecificOutput\":{\"hookEventName\":\"PreToolUse\",\"permissionDecision\":\"ask\",\"permissionDecisionReason\":\"STOP: Read .github/agents/pr-and-commit-rules.md FIRST, then create the PR following its rules (title prefix, labels, blank template).\"}}'",
+            "statusMessage": "Checking PR creation rules..."
+          }
+        ]
+      }
+    ]
+  }
+}

.cursor/rules/pr-and-commit.mdc

@@ -0,0 +1,74 @@
+---
+description: Rules for AI-generated commits and pull requests
+globs:
+alwaysApply: true
+---
+
+# PR and Commit Rules for AI Agents
+
+Canonical source: `.github/agents/pr-and-commit-rules.md`
+
+## Commit Rules
+
+### [AI] Prefix Requirement
+
+**ALL commit messages MUST be prefixed with `[AI]`.** This is a mandatory requirement with no exceptions.
+
+**Examples:**
+
+- `[AI] Fix type error in account validation`
+- `[AI] Add support for new transaction categories`
+- `Fix type error in account validation` (MISSING PREFIX - NOT ALLOWED)
+- `Add support for new transaction categories` (MISSING PREFIX - NOT ALLOWED)
+
+### Git Safety Rules
+
+- **Never** update git config
+- **Never** run destructive git operations (force push, hard reset) unless the user explicitly requests it
+- **Never** skip hooks (`--no-verify`, `--no-gpg-sign`)
+- **Never** force push to `main`/`master`
+- **Never** commit unless explicitly asked by the user
+
+## Pre-Commit Quality Checklist
+
+Before committing, ensure all of the following:
+
+- [ ] Commit message is prefixed with `[AI]`
+- [ ] `yarn typecheck` passes
+- [ ] `yarn lint:fix` has been run
+- [ ] Relevant tests pass
+- [ ] User-facing strings are translated
+- [ ] Code style conventions followed (see `AGENTS.md` for full style guide)
+
+## Pull Request Rules
+
+### [AI] Prefix Requirement
+
+**ALL pull request titles MUST be prefixed with `[AI]`.** This is a mandatory requirement with no exceptions.
+
+**Examples:**
+
+- `[AI] Fix type error in account validation`
+- `[AI] Add support for new transaction categories`
+- `Fix type error in account validation` (MISSING PREFIX - NOT ALLOWED)
+
+### Labels
+
+Add the **"AI generated"** label to all AI-created pull requests.
+
+### PR Template: Do Not Fill In
+
+- **NEVER fill in the PR template** (`.github/PULL_REQUEST_TEMPLATE.md`). Leave all blank spaces and placeholder comments as-is.
+- **Exception**: If a human **explicitly asks** you to fill out the PR template, then fill it out **in Chinese** (简体中文).
+
+## Quick-Reference Workflow
+
+1. Make your changes
+2. Run `yarn typecheck` — fix any errors
+3. Run `yarn lint:fix` — fix any remaining lint errors
+4. Run relevant tests (`yarn test` for all, or workspace-specific)
+5. Stage files and commit with `[AI]` prefix — do not skip hooks
+6. When creating a PR:
+   - Use `[AI]` prefix in the title
+   - Add the `"AI generated"` label
+   - Leave the PR template blank (do not fill it in)

.github/actions/ai-generated-release-notes/create-release-notes-file.js

@@ -16,14 +16,19 @@ if (!token || !repo || !issueNumber || !summaryDataJson || !category) {
 const [owner, repoName] = repo.split('/');
 const octokit = new Octokit({ auth: token });
 
+const VALID_CATEGORIES = [
+  'Features',
+  'Bugfixes',
+  'Enhancements',
+  'Maintenance',
+];
+const GITHUB_USERNAME_RE =
+  /^[a-zA-Z0-9](?:[a-zA-Z0-9]|-(?=[a-zA-Z0-9])){0,38}$/;
+
 async function createReleaseNotesFile() {
   try {
     const summaryData = JSON.parse(summaryDataJson);
 
-    console.log('Debug - Category value:', category);
-    console.log('Debug - Category type:', typeof category);
-    console.log('Debug - Category JSON stringified:', JSON.stringify(category));
-
     if (!summaryData) {
       console.log('No summary data available, cannot create file');
       return;
@@ -34,26 +39,62 @@ async function createReleaseNotesFile() {
       return;
     }
 
-    // Create file content - ensure category is not quoted
+    // Normalize category - strip surrounding quotes and validate against allow-list
     const cleanCategory =
       typeof category === 'string'
         ? category.replace(/^["']|["']$/g, '')
         : category;
-    console.log('Debug - Clean category:', cleanCategory);
+
+    if (!VALID_CATEGORIES.includes(cleanCategory)) {
+      console.log(
+        `Invalid category "${cleanCategory}". Must be one of: ${VALID_CATEGORIES.join(', ')}`,
+      );
+      return;
+    }
+
+    // Validate author is a plausible GitHub username
+    const author = String(summaryData.author || '');
+    if (!GITHUB_USERNAME_RE.test(author)) {
+      console.log(
+        `Invalid author "${author}", aborting release notes creation`,
+      );
+      return;
+    }
+
+    // Normalize summary: collapse whitespace to a single line so it cannot
+    // introduce extra YAML frontmatter or break the markdown structure.
+    const cleanSummary = String(summaryData.summary || '')
+      .replace(/\s+/g, ' ')
+      .trim();
+    if (!cleanSummary) {
+      console.log('Empty summary, aborting release notes creation');
+      return;
+    }
+
+    // Validate PR number - must be a positive integer. The value comes from
+    // the GitHub API, but we harden it because it's used to build a file path
+    // and a commit message.
+    const validatedPrNumber = Number(summaryData.prNumber);
+    if (!Number.isInteger(validatedPrNumber) || validatedPrNumber <= 0) {
+      console.log(
+        `Invalid PR number "${summaryData.prNumber}", aborting release notes creation`,
+      );
+      return;
+    }
 
     const fileContent = `---
 category: ${cleanCategory}
-authors: [${summaryData.author}]
+authors: [${author}]
 ---
 
-${summaryData.summary}
+${cleanSummary}
 `;
 
-    const fileName = `upcoming-release-notes/${summaryData.prNumber}.md`;
+    const fileName = `upcoming-release-notes/${validatedPrNumber}.md`;
 
-    console.log(`Creating release notes file: ${fileName}`);
-    console.log('File content:');
-    console.log(fileContent);
+    console.log(
+      `Creating release notes file: ${fileName} (category: ${cleanCategory}, author: ${author})`,
+    );
 
     // Get PR info
     const { data: pr } = await octokit.rest.pulls.get({
@@ -75,7 +116,7 @@ ${summaryData.summary}
       owner: headOwner,
       repo: headRepo,
       path: fileName,
-      message: `Add release notes for PR #${summaryData.prNumber}`,
+      message: `Add release notes for PR #${validatedPrNumber}`,
       content: Buffer.from(fileContent).toString('base64'),
       branch: prBranch,
       committer: {

.github/actions/ai-generated-release-notes/generate-summary.js

@@ -25,8 +25,6 @@ try {
     process.exit(0);
   }
 
-  console.log('CodeRabbit comment body:', commentBody);
-
   const data = JSON.stringify({
     model: 'gpt-4o-mini',
     messages: [

.github/actions/docs-spelling/expect.txt

@@ -2,7 +2,9 @@ Abanca
 ABNAMRO
 ABNANL
 Activo
+actualrc
 AESUDEF
+ajv
 ALZEY
 Anglais
 ANZ
@@ -110,7 +112,6 @@ KBCBE
 Keycloak
 Khurozov
 KORT
-KRW
 Kreditbank
 lage
 LHV
@@ -132,6 +133,8 @@ overbudgeting
 oxc
 Paribas
 passwordless
+PAYPAL
+picomatch
 pluggyai
 Poste
 PPABPLPK
@@ -172,8 +175,11 @@ tada
 taskbar
 templating
 THB
+TIMEFRAME
 touchscreen
 triaging
+tsgo
+TWD
 UAH
 ubuntu
 undici

.github/actions/release-notes/check/action.yml

@@ -0,0 +1,17 @@
+name: Check release notes
+description: Validate that a PR includes a properly formatted release note file
+
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+      with:
+        node-version: 22
+    - name: Install dependencies
+      shell: bash
+      run: yarn --immutable
+    - name: Check release notes
+      env:
+        PR_NUMBER: ${{ github.event.pull_request.number }}
+      shell: bash
+      run: node packages/ci-actions/bin/release-notes-check.mjs

.github/actions/release-notes/generate/action.yml

@@ -0,0 +1,17 @@
+name: Generate release notes
+description: Generate release documentation from release note files
+
+runs:
+  using: composite
+  steps:
+    - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
+      with:
+        node-version: 22
+    - name: Install dependencies
+      shell: bash
+      run: yarn --immutable
+    - name: Generate release notes
+      shell: bash
+      env:
+        GITHUB_TOKEN: ${{ github.token }}
+      run: node packages/ci-actions/bin/release-notes-generate.mjs

.github/actions/setup/action.yml

@@ -15,7 +15,7 @@ runs:
   using: composite
   steps:
     - name: Install node
-      uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
+      uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
       with:
         node-version: 22
     - name: Install yarn
@@ -27,7 +27,7 @@ runs:
       run: echo "version=$(node -v)" >> "$GITHUB_OUTPUT"
       shell: bash
     - name: Cache
-      uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+      uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
       id: cache
       with:
         path: ${{ format('{0}/**/node_modules', inputs.working-directory) }}
@@ -36,7 +36,7 @@ runs:
       run: mkdir -p ${{ format('{0}/.lage', inputs.working-directory) }}
       shell: bash
     - name: Cache Lage
-      uses: actions/cache@0057852bfaa89a56745cba8c7296529d2fc39830 # v4.3.0
+      uses: actions/cache@cdf6c1fa76f9f475f3d7449005a359c84ca0f306 # v5.0.3
       with:
         path: ${{ format('{0}/.lage', inputs.working-directory) }}
         key: lage-${{ runner.os }}-${{ github.sha }}
@@ -48,7 +48,7 @@ runs:
       shell: bash
       if: steps.cache.outputs.cache-hit != 'true'
     - name: Download translations
-      uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       with:
         repository: actualbudget/translations
         path: ${{ inputs.working-directory }}/packages/desktop-client/locale

.github/agents/pr-and-commit-rules.md

@@ -0,0 +1,70 @@
+# PR and Commit Rules for AI Agents
+
+This is the single source of truth for all commit and pull request rules that AI agents must follow when working with Actual Budget.
+
+## Commit Rules
+
+### [AI] Prefix Requirement
+
+**ALL commit messages MUST be prefixed with `[AI]`.** This is a mandatory requirement with no exceptions.
+
+**Examples:**
+
+- `[AI] Fix type error in account validation`
+- `[AI] Add support for new transaction categories`
+- `Fix type error in account validation` (MISSING PREFIX - NOT ALLOWED)
+- `Add support for new transaction categories` (MISSING PREFIX - NOT ALLOWED)
+
+### Git Safety Rules
+
+- **Never** update git config
+- **Never** run destructive git operations (force push, hard reset) unless the user explicitly requests it
+- **Never** skip hooks (`--no-verify`, `--no-gpg-sign`)
+- **Never** force push to `main`/`master`
+- **Never** commit unless explicitly asked by the user
+
+## Pre-Commit Quality Checklist
+
+Before committing, ensure all of the following:
+
+- [ ] Commit message is prefixed with `[AI]`
+- [ ] `yarn typecheck` passes
+- [ ] `yarn lint:fix` has been run
+- [ ] Relevant tests pass
+- [ ] User-facing strings are translated
+- [ ] Code style conventions followed (see `AGENTS.md` for full style guide)
+
+## Pull Request Rules
+
+### [AI] Prefix Requirement
+
+**ALL pull request titles MUST be prefixed with `[AI]`.** This is a mandatory requirement with no exceptions.
+
+**Examples:**
+
+- `[AI] Fix type error in account validation`
+- `[AI] Add support for new transaction categories`
+- `Fix type error in account validation` (MISSING PREFIX - NOT ALLOWED)
+
+### Labels
+
+Add the **"AI generated"** label to all AI-created pull requests. This helps maintainers understand the nature of the contribution.
+
+### PR Template: Do Not Fill In
+
+- **NEVER fill in the PR template** (`.github/PULL_REQUEST_TEMPLATE.md`). Leave all blank spaces and placeholder comments as-is. Humans are expected to fill in the Description, Related issue(s), Testing, and Checklist sections.
+- **Exception**: If a human **explicitly asks** you to fill out the PR template, then fill it out **in Chinese**, using Chinese characters (简体中文) for all content you add.
+
+## Quick-Reference Workflow
+
+Follow these steps when committing and creating PRs:
+
+1. Make your changes
+2. Run `yarn typecheck` — fix any errors
+3. Run `yarn lint:fix` — fix any remaining lint errors
+4. Run relevant tests (`yarn test` for all, or workspace-specific)
+5. Stage files and commit with `[AI]` prefix — do not skip hooks
+6. When creating a PR:
+   - Use `[AI]` prefix in the title
+   - Add the `"AI generated"` label
+   - Leave the PR template blank (do not fill it in)

.github/scripts/count-points.mjs

@@ -35,7 +35,11 @@ const CONFIG = {
     'release-notes/**/*',
     'upcoming-release-notes/**/*',
   ],
-  DOCS_FILES_PATTERN: 'packages/docs/**/*',
+  DOCS_FILES_PATTERNS: [
+    'packages/docs/**/*',
+    '!packages/docs/package.json',
+    '.github/actions/docs-spelling/*',
+  ],
 };
 
 /**
@@ -57,78 +61,29 @@ function parseReleaseNotesCategory(content) {
   return categoryMatch[1].trim();
 }
 
-/**
- * Get the last commit SHA on or before a given date.
- * @param {Octokit} octokit - The Octokit instance.
- * @param {string} owner - Repository owner.
- * @param {string} repo - Repository name.
- * @param {Date} beforeDate - The date to find the last commit before.
- * @returns {Promise<string|null>} The commit SHA or null if not found.
- */
-async function getLastCommitBeforeDate(octokit, owner, repo, beforeDate) {
-  try {
-    // Get the default branch from the repository
-    const { data: repoData } = await octokit.repos.get({ owner, repo });
-    const defaultBranch = repoData.default_branch;
-
-    const { data: commits } = await octokit.repos.listCommits({
-      owner,
-      repo,
-      sha: defaultBranch,
-      until: beforeDate.toISOString(),
-      per_page: 1,
-    });
-
-    if (commits.length > 0) {
-      return commits[0].sha;
-    }
-  } catch {
-    // If error occurs, return null to fall back to default branch
-  }
-
-  return null;
-}
-
 /**
  * Get the category and points for a PR by reading its release notes file.
  * @param {Octokit} octokit - The Octokit instance.
  * @param {string} owner - Repository owner.
  * @param {string} repo - Repository name.
- * @param {number} prNumber - PR number.
- * @param {Date} monthEnd - The end date of the month to use as base revision.
- * @returns {Promise<Object>} Object with category and points, or null if error.
+ * @param {string|null} releaseNoteBlobSha - The blob SHA of the release notes file, or null if not found.
+ * @returns {Promise<Object>} Object with category and points.
  */
 async function getPRCategoryAndPoints(
   octokit,
   owner,
   repo,
-  prNumber,
-  monthEnd,
+  releaseNoteBlobSha,
 ) {
-  const releaseNotesPath = `upcoming-release-notes/${prNumber}.md`;
-
   try {
-    // Get the last commit of the month to use as base revision
-    const commitSha = await getLastCommitBeforeDate(
-      octokit,
-      owner,
-      repo,
-      monthEnd,
-    );
+    if (releaseNoteBlobSha) {
+      const { data: blob } = await octokit.git.getBlob({
+        owner,
+        repo,
+        file_sha: releaseNoteBlobSha,
+      });
 
-    // Try to read the release notes file from the last commit of the month
-    const { data: fileContent } = await octokit.repos.getContent({
-      owner,
-      repo,
-      path: releaseNotesPath,
-      ref: commitSha || undefined, // Use commit SHA if available, otherwise default branch
-    });
-
-    if (fileContent.content) {
-      // Decode base64 content
-      const content = Buffer.from(fileContent.content, 'base64').toString(
-        'utf-8',
-      );
+      const content = Buffer.from(blob.content, 'base64').toString('utf-8');
       const category = parseReleaseNotesCategory(content);
       const tier = CONFIG.PR_CONTRIBUTION_POINTS.find(e =>
         e.categories.includes(category),
@@ -276,13 +231,25 @@ async function countContributorPoints() {
             ),
         );
 
-        const docsFiles = filteredFiles.filter(file =>
-          minimatch(file.filename, CONFIG.DOCS_FILES_PATTERN, { dot: true }),
-        );
-        const codeFiles = filteredFiles.filter(
-          file =>
-            !minimatch(file.filename, CONFIG.DOCS_FILES_PATTERN, { dot: true }),
-        );
+        const isDocsFile = file => {
+          const positivePatterns = CONFIG.DOCS_FILES_PATTERNS.filter(
+            p => !p.startsWith('!'),
+          );
+          const negativePatterns = CONFIG.DOCS_FILES_PATTERNS.filter(p =>
+            p.startsWith('!'),
+          );
+          return (
+            positivePatterns.some(p =>
+              minimatch(file.filename, p, { dot: true }),
+            ) &&
+            negativePatterns.every(p =>
+              minimatch(file.filename, p, { dot: true }),
+            )
+          );
+        };
+
+        const docsFiles = filteredFiles.filter(isDocsFile);
+        const codeFiles = filteredFiles.filter(file => !isDocsFile(file));
 
         const docsChanges = docsFiles.reduce(
           (sum, file) => sum + file.additions + file.deletions,
@@ -329,12 +296,15 @@ async function countContributorPoints() {
           // Award points to PR author if they are a core maintainer
           const prAuthor = pr.user?.login;
           if (prAuthor && orgMemberLogins.has(prAuthor)) {
+            const releaseNoteFile = modifiedFiles.find(
+              file =>
+                file.filename === `upcoming-release-notes/${pr.number}.md`,
+            );
             const categoryAndPoints = await getPRCategoryAndPoints(
               octokit,
               owner,
               repo,
-              pr.number,
-              until,
+              releaseNoteFile?.sha ?? null,
             );
 
             if (categoryAndPoints) {

.github/workflows/ai-generated-release-notes.yml

@@ -17,7 +17,7 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Set up environment
         uses: ./.github/actions/setup
         with:

.github/workflows/autofix.yml

@@ -15,11 +15,11 @@ jobs:
   autofix:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
           download-translations: 'false'
       - name: Format code
         run: yarn lint:fix
-      - uses: autofix-ci/action@635ffb0c9798bd160680f18fd73371e355b85f27
+      - uses: autofix-ci/action@7a166d7532b277f34e16238930461bf77f9d7ed8 # v1.3.3

.github/workflows/build.yml

@@ -22,7 +22,7 @@ jobs:
   api:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
@@ -34,12 +34,12 @@ jobs:
       - name: Prepare bundle stats artifact
         run: cp packages/api/app/stats.json api-stats.json
       - name: Upload Build
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: actual-api
           path: packages/api/actual-api.tgz
       - name: Upload API bundle stats
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: api-build-stats
           path: api-stats.json
@@ -47,7 +47,7 @@ jobs:
   crdt:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
@@ -57,7 +57,7 @@ jobs:
       - name: Create package tgz
         run: cd packages/crdt && yarn pack && mv package.tgz actual-crdt.tgz
       - name: Upload Build
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: actual-crdt
           path: packages/crdt/actual-crdt.tgz
@@ -65,26 +65,51 @@ jobs:
   web:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Set up environment
         uses: ./.github/actions/setup
       - name: Build Web
         run: yarn build:browser
       - name: Upload Build
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: actual-web
           path: packages/desktop-client/build
       - name: Upload Build Stats
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: build-stats
           path: packages/desktop-client/build-stats
 
+  cli:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Set up environment
+        uses: ./.github/actions/setup
+        with:
+          download-translations: 'false'
+      - name: Build CLI
+        run: yarn build:cli
+      - name: Create package tgz
+        run: cd packages/cli && yarn pack && mv package.tgz actual-cli.tgz
+      - name: Prepare bundle stats artifact
+        run: cp packages/cli/dist/stats.json cli-stats.json
+      - name: Upload Build
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        with:
+          name: actual-cli
+          path: packages/cli/actual-cli.tgz
+      - name: Upload CLI bundle stats
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
+        with:
+          name: cli-build-stats
+          path: cli-stats.json
+
   server:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
@@ -92,7 +117,7 @@ jobs:
       - name: Build Server
         run: yarn workspace @actual-app/sync-server build
       - name: Upload Build
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: sync-server
           path: packages/sync-server/build

.github/workflows/check.yml

@@ -12,10 +12,20 @@ concurrency:
   cancel-in-progress: ${{ github.ref != 'refs/heads/master' }}
 
 jobs:
+  constraints:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Set up environment
+        uses: ./.github/actions/setup
+        with:
+          download-translations: 'false'
+      - name: Check dependency version consistency
+        run: yarn constraints
   lint:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
@@ -25,7 +35,7 @@ jobs:
   typecheck:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
@@ -35,7 +45,7 @@ jobs:
   validate-cli:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
@@ -47,7 +57,7 @@ jobs:
   test:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
@@ -59,9 +69,10 @@ jobs:
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
-      - uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - name: Set up environment
+        uses: ./.github/actions/setup
         with:
-          node-version: 22
+          download-translations: 'false'
       - name: Check migrations
-        run: node ./.github/actions/check-migrations.js
+        run: yarn workspace @actual-app/ci-actions tsx bin/check-migrations.ts

.github/workflows/claude-code-review.yml

@@ -1,44 +0,0 @@
-name: Claude Code Review
-
-on:
-  pull_request:
-    types: [opened, synchronize, ready_for_review, reopened]
-    # Optional: Only run on specific file changes
-    # paths:
-    #   - "src/**/*.ts"
-    #   - "src/**/*.tsx"
-    #   - "src/**/*.js"
-    #   - "src/**/*.jsx"
-
-jobs:
-  claude-review:
-    # Optional: Filter by PR author
-    # if: |
-    #   github.event.pull_request.user.login == 'external-contributor' ||
-    #   github.event.pull_request.user.login == 'new-developer' ||
-    #   github.event.pull_request.author_association == 'FIRST_TIME_CONTRIBUTOR'
-
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pull-requests: read
-      issues: read
-      id-token: write
-
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 1
-
-      - name: Run Claude Code Review
-        id: claude-review
-        uses: anthropics/claude-code-action@v1
-        with:
-          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-          plugin_marketplaces: 'https://github.com/anthropics/claude-code.git'
-          plugins: 'code-review@claude-code-plugins'
-          prompt: '/code-review:code-review ${{ github.repository }}/pull/${{ github.event.pull_request.number }}'
-          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
-          # or https://code.claude.com/docs/en/cli-reference for available options
-

.github/workflows/claude.yml

@@ -1,50 +0,0 @@
-name: Claude Code
-
-on:
-  issue_comment:
-    types: [created]
-  pull_request_review_comment:
-    types: [created]
-  issues:
-    types: [opened, assigned]
-  pull_request_review:
-    types: [submitted]
-
-jobs:
-  claude:
-    if: |
-      (github.event_name == 'issue_comment' && contains(github.event.comment.body, '@claude')) ||
-      (github.event_name == 'pull_request_review_comment' && contains(github.event.comment.body, '@claude')) ||
-      (github.event_name == 'pull_request_review' && contains(github.event.review.body, '@claude')) ||
-      (github.event_name == 'issues' && (contains(github.event.issue.body, '@claude') || contains(github.event.issue.title, '@claude')))
-    runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pull-requests: read
-      issues: read
-      id-token: write
-      actions: read # Required for Claude to read CI results on PRs
-    steps:
-      - name: Checkout repository
-        uses: actions/checkout@v4
-        with:
-          fetch-depth: 1
-
-      - name: Run Claude Code
-        id: claude
-        uses: anthropics/claude-code-action@v1
-        with:
-          claude_code_oauth_token: ${{ secrets.CLAUDE_CODE_OAUTH_TOKEN }}
-
-          # This is an optional setting that allows Claude to read CI results on PRs
-          additional_permissions: |
-            actions: read
-
-          # Optional: Give a custom prompt to Claude. If this is not specified, Claude will perform the instructions specified in the comment that tagged it.
-          # prompt: 'Update the pull request description to include a summary of changes.'
-
-          # Optional: Add claude_args to customize behavior and configuration
-          # See https://github.com/anthropics/claude-code-action/blob/main/docs/usage.md
-          # or https://code.claude.com/docs/en/cli-reference for available options
-          # claude_args: '--allowed-tools Bash(gh pr:*)'
-

.github/workflows/codeql.yml

@@ -22,14 +22,14 @@ jobs:
 
     steps:
       - name: Checkout repository
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v3
+        uses: github/codeql-action/init@b1bff81932f5cdfc8695c7752dcee935dcd061c8 # v4.33.0
         with:
           languages: javascript
 
       - name: Perform CodeQL Analysis
-        uses: github/codeql-action/analyze@v3
+        uses: github/codeql-action/analyze@b1bff81932f5cdfc8695c7752dcee935dcd061c8 # v4.33.0
         with:
           category: '/language:javascript'

.github/workflows/count-points.yml

@@ -16,7 +16,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout repository
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Set up environment
         uses: ./.github/actions/setup
         with:

.github/workflows/docker-edge.yml

@@ -36,17 +36,17 @@ jobs:
       matrix:
         os: [ubuntu, alpine]
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130 # v3.7.0
+        uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a # v4.0.0
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3.11.1
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@318604b99e75e41977312d83839a89be02ca4893 # v5.9.0
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
         with:
           # Push to both Docker Hub and Github Container Registry
           images: ${{ env.IMAGES }}
@@ -54,14 +54,14 @@ jobs:
           tags: ${{ env.TAGS }}
 
       - name: Login to Docker Hub
-        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4.0.0
         if: github.event_name != 'pull_request' && !github.event.repository.fork
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Login to GitHub Container Registry
-        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4.0.0
         if: github.event_name != 'pull_request'
         with:
           registry: ghcr.io
@@ -76,7 +76,7 @@ jobs:
         run: yarn build:server
 
       - name: Build image for testing
-        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
+        uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7.0.0
         with:
           context: .
           push: false
@@ -87,13 +87,13 @@ jobs:
       - name: Test that the docker image boots
         run: |
           docker run --detach --network=host actualbudget/actual-server-testing
-          sleep 5
-          curl --fail -sS -LI -w '%{http_code}\n' --retry 10 --retry-delay 1 --retry-connrefused localhost:5006
+          sleep 10
+          curl --fail -sS -LI -w '%{http_code}\n' --retry 20 --retry-delay 1 --retry-connrefused localhost:5006
 
       # This will use the cache from the earlier build step and not rebuild the image
       # https://docs.docker.com/build/ci/github-actions/test-before-push/
       - name: Build and push images
-        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
+        uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7.0.0
         with:
           context: .
           push: ${{ github.event_name != 'pull_request' }}

.github/workflows/docker-release.yml

@@ -28,17 +28,17 @@ jobs:
     name: Build Docker image
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Set up QEMU
-        uses: docker/setup-qemu-action@c7c53464625b32c7a7e944ae62b3e17d2b600130 # v3.7.0
+        uses: docker/setup-qemu-action@ce360397dd3f832beb865e1373c09c0e9f86d70a # v4.0.0
 
       - name: Set up Docker Buildx
-        uses: docker/setup-buildx-action@e468171a9de216ec08956ac3ada2f0791b6bd435 # v3.11.1
+        uses: docker/setup-buildx-action@4d04d5d9486b7bd6fa91e7baf45bbb4f8b9deedd # v4.0.0
 
       - name: Docker meta
         id: meta
-        uses: docker/metadata-action@318604b99e75e41977312d83839a89be02ca4893 # v5.9.0
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
         with:
           # Push to both Docker Hub and Github Container Registry
           images: ${{ env.IMAGES }}
@@ -48,7 +48,7 @@ jobs:
 
       - name: Docker meta for Alpine image
         id: alpine-meta
-        uses: docker/metadata-action@318604b99e75e41977312d83839a89be02ca4893 # v5.9.0
+        uses: docker/metadata-action@030e881283bb7a6894de51c315a6bfe6a94e05cf # v6.0.0
         with:
           images: ${{ env.IMAGES }}
           # Automatically update :latest
@@ -58,13 +58,13 @@ jobs:
           tags: ${{ env.TAGS }}
 
       - name: Login to Docker Hub
-        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4.0.0
         with:
           username: ${{ secrets.DOCKERHUB_USERNAME }}
           password: ${{ secrets.DOCKERHUB_TOKEN }}
 
       - name: Login to GitHub Container Registry
-        uses: docker/login-action@5e57cd118135c172c3672efd75eb46360885c0ef # v3.6.0
+        uses: docker/login-action@b45d80f862d83dbcd57f89517bcf500b2ab88fb2 # v4.0.0
         with:
           registry: ghcr.io
           username: ${{ github.repository_owner }}
@@ -78,7 +78,7 @@ jobs:
         run: yarn build:server
 
       - name: Build and push ubuntu image
-        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
+        uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7.0.0
         with:
           context: .
           push: true
@@ -87,7 +87,7 @@ jobs:
           tags: ${{ steps.meta.outputs.tags }}
 
       - name: Build and push alpine image
-        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
+        uses: docker/build-push-action@d08e5c354a6adb9ed34480a06d141179aa583294 # v7.0.0
         with:
           context: .
           push: true

.github/workflows/docs-spelling.yml

@@ -79,12 +79,12 @@ jobs:
     steps:
       - name: check-spelling
         id: spelling
-        uses: check-spelling/check-spelling@main
+        uses: check-spelling/check-spelling@cfb6f7e75bbfc89c71eaa30366d0c166f1bd9c8c # main
         with:
           suppress_push_for_open_pull_request: 1
           checkout: true
           check_file_names: 1
-          spell_check_this: check-spelling/spell-check-this@prerelease
+          spell_check_this: check-spelling/spell-check-this@92453f59cac8985482dfc301a8ece4c6d7de8a0c # prerelease
           post_comment: 0
           use_magic_file: 1
           experimental_apply_changes_via_bot: 1
@@ -114,10 +114,10 @@ jobs:
     if: (success() || failure()) && needs.spelling.outputs.followup && github.event_name == 'push'
     steps:
       - name: comment
-        uses: check-spelling/check-spelling@main
+        uses: check-spelling/check-spelling@cfb6f7e75bbfc89c71eaa30366d0c166f1bd9c8c # main
         with:
           checkout: true
-          spell_check_this: check-spelling/spell-check-this@prerelease
+          spell_check_this: check-spelling/spell-check-this@92453f59cac8985482dfc301a8ece4c6d7de8a0c # prerelease
           task: ${{ needs.spelling.outputs.followup }}
           config: .github/actions/docs-spelling
 
@@ -131,10 +131,10 @@ jobs:
     if: (success() || failure()) && needs.spelling.outputs.followup && contains(github.event_name, 'pull_request')
     steps:
       - name: comment
-        uses: check-spelling/check-spelling@main
+        uses: check-spelling/check-spelling@cfb6f7e75bbfc89c71eaa30366d0c166f1bd9c8c # main
         with:
           checkout: true
-          spell_check_this: check-spelling/spell-check-this@prerelease
+          spell_check_this: check-spelling/spell-check-this@92453f59cac8985482dfc301a8ece4c6d7de8a0c # prerelease
           task: ${{ needs.spelling.outputs.followup }}
           experimental_apply_changes_via_bot: 1
           config: .github/actions/docs-spelling
@@ -156,7 +156,7 @@ jobs:
       cancel-in-progress: false
     steps:
       - name: apply spelling updates
-        uses: check-spelling/check-spelling@main
+        uses: check-spelling/check-spelling@cfb6f7e75bbfc89c71eaa30366d0c166f1bd9c8c # main
         with:
           experimental_apply_changes_via_bot: 1
           checkout: true

.github/workflows/e2e-test.yml

@@ -32,7 +32,7 @@ jobs:
     container:
       image: mcr.microsoft.com/playwright:v1.58.2-jammy
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
@@ -41,7 +41,7 @@ jobs:
         run: git config --global --add safe.directory "$GITHUB_WORKSPACE"
       - name: Run E2E Tests
         run: yarn e2e --shard=${{ matrix.shard }}/5
-      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+      - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         if: always()
         with:
           name: desktop-client-test-results-shard-${{ matrix.shard }}
@@ -55,7 +55,7 @@ jobs:
     container:
       image: mcr.microsoft.com/playwright:v1.58.2-jammy
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
@@ -65,7 +65,7 @@ jobs:
       - name: Run Desktop app E2E Tests
         run: |
           xvfb-run --auto-servernum --server-args="-screen 0 1920x1080x24" -- yarn e2e:desktop
-      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+      - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         if: always()
         with:
           name: desktop-app-test-results
@@ -83,14 +83,14 @@ jobs:
     container:
       image: mcr.microsoft.com/playwright:v1.58.2-jammy
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Set up environment
         uses: ./.github/actions/setup
         with:
           download-translations: 'false'
       - name: Run VRT Tests
         run: yarn vrt --shard=${{ matrix.shard }}/5
-      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+      - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         if: always()
         with:
           name: vrt-blob-report-${{ matrix.shard }}
@@ -106,11 +106,11 @@ jobs:
     container:
       image: mcr.microsoft.com/playwright:v1.58.2-jammy
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - name: Set up environment
         uses: ./.github/actions/setup
       - name: Download all blob reports
-        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           path: packages/desktop-client/all-blob-reports
           pattern: vrt-blob-report-*
@@ -118,7 +118,7 @@ jobs:
       - name: Merge reports
         id: merge-reports
         run: yarn workspace @actual-app/web run playwright merge-reports --reporter html ./all-blob-reports
-      - uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+      - uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         id: playwright-report-vrt
         with:
           name: html-report--attempt-${{ github.run_attempt }}
@@ -134,7 +134,7 @@ jobs:
           echo "${{ steps.playwright-report-vrt.outputs.artifact-url }}" > vrt-metadata/artifact-url.txt
       - name: Upload VRT metadata
         if: github.event_name == 'pull_request'
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: vrt-comment-metadata
           path: vrt-metadata/

.github/workflows/e2e-vrt-comment.yml

@@ -18,7 +18,7 @@ jobs:
     if: github.event.workflow_run.event == 'pull_request'
     steps:
       - name: Download VRT metadata
-        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           run-id: ${{ github.event.workflow_run.id }}
@@ -53,7 +53,7 @@ jobs:
 
       - name: Comment on PR with VRT report link
         if: steps.metadata.outputs.should_comment == 'true'
-        uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 # v2.9.4
+        uses: marocchino/sticky-pull-request-comment@70d2764d1a7d5d9560b100cbea0077fc8f633987 # v3.0.2
         with:
           number: ${{ steps.metadata.outputs.pr_number }}
           header: vrt-comment

.github/workflows/electron-master.yml

@@ -29,7 +29,7 @@ jobs:
           - macos-latest
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - if: ${{ startsWith(matrix.os, 'windows') }}
         run: pip.exe install setuptools
       - if: ${{ ! startsWith(matrix.os, 'windows') }}
@@ -74,7 +74,7 @@ jobs:
         if: ${{ ! startsWith(matrix.os, 'macos') }}
         run: ./bin/package-electron
       - name: Upload Build
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: actual-electron-${{ matrix.os }}
           path: |
@@ -85,13 +85,13 @@ jobs:
             packages/desktop-electron/dist/*.flatpak
       - name: Upload Windows Store Build
         if: ${{ startsWith(matrix.os, 'windows') }}
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: actual-electron-${{ matrix.os }}-appx
           path: |
             packages/desktop-electron/dist/*.appx
       - name: Add to new release
-        uses: softprops/action-gh-release@5be0e66d93ac7ed76da52eca8bb058f665c3a5fe # v2.4.2
+        uses: softprops/action-gh-release@153bb8e04406b158c6c84fc1615b65b24149a1fe # v2.6.1
         with:
           draft: true
           body: |
@@ -126,7 +126,7 @@ jobs:
           Install-Module -Name StoreBroker -AcceptLicense -Force -Scope CurrentUser -Verbose
 
       - name: Download Microsoft Store artifacts
-        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: actual-electron-windows-latest-appx
 

.github/workflows/electron-pr.yml

@@ -33,7 +33,7 @@ jobs:
           - macos-latest
     runs-on: ${{ matrix.os }}
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - if: ${{ startsWith(matrix.os, 'windows') }}
         run: pip.exe install setuptools
       - if: ${{ ! startsWith(matrix.os, 'windows') }}
@@ -42,6 +42,8 @@ jobs:
           python3 -m venv .venv
           source .venv/bin/activate
           python3 -m pip install setuptools
+      - name: Set up environment
+        uses: ./.github/actions/setup
       - if: ${{ startsWith(matrix.os, 'ubuntu') }}
         name: Setup Flatpak dependencies
         run: |
@@ -56,65 +58,63 @@ jobs:
 
           METAINFO_FILE="packages/desktop-electron/extra-resources/linux/com.actualbudget.actual.metainfo.xml"
           TODAY=$(date +%Y-%m-%d)
-          VERSION=$(node ./packages/ci-actions/bin/get-next-package-version.js --package-json ./packages/desktop-electron/package.json --type nightly)
+          VERSION=$(yarn workspace @actual-app/ci-actions tsx bin/get-next-package-version.ts --package-json ./packages/desktop-electron/package.json --type nightly)
           sed -i "s/%RELEASE_VERSION%/$VERSION/g; s/%RELEASE_DATE%/$TODAY/g" "$METAINFO_FILE"
           flatpak run --command=flatpak-builder-lint org.flatpak.Builder appstream "$METAINFO_FILE"
-      - name: Set up environment
-        uses: ./.github/actions/setup
       - name: Build Electron
         run: ./bin/package-electron
 
       - name: Upload Linux x64 AppImage
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: Actual-linux-x86_64.AppImage
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-linux-x86_64.AppImage
 
       - name: Upload Linux arm64 AppImage
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: Actual-linux-arm64.AppImage
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-linux-arm64.AppImage
 
       - name: Upload Linux x64 flatpak
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: Actual-linux-x86_64.flatpak
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-linux-x86_64.flatpak
 
       - name: Upload Windows x32 exe
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: Actual-windows-ia32.exe
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-windows-ia32.exe
 
       - name: Upload Windows x64 exe
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: Actual-windows-x64.exe
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-windows-x64.exe
 
       - name: Upload Windows arm64 exe
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: Actual-windows-arm64.exe
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-windows-arm64.exe
 
       - name: Upload Mac x64 dmg
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: Actual-mac-x64.dmg
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-mac-x64.dmg
 
       - name: Upload Mac arm64 dmg
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: Actual-mac-arm64.dmg
           if-no-files-found: ignore
@@ -122,7 +122,7 @@ jobs:
 
       - name: Upload Windows Store Build
         if: ${{ startsWith(matrix.os, 'windows') }}
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: actual-electron-${{ matrix.os }}-appx
           path: |

.github/workflows/fork-pr-welcome.yml

@@ -25,7 +25,7 @@ jobs:
     if: github.event.pull_request.head.repo.full_name != github.repository
     steps:
       - name: Post welcome comment
-        uses: marocchino/sticky-pull-request-comment@773744901bac0e8cbb5a0dc842800d45e9b2b405 # v2.9.4
+        uses: marocchino/sticky-pull-request-comment@70d2764d1a7d5d9560b100cbea0077fc8f633987 # v3.0.2
         with:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
           number: ${{ github.event.pull_request.number }}

.github/workflows/generate-release-pr.yml

@@ -17,44 +17,54 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           ref: ${{ github.event.inputs.ref }}
+      - name: Set up environment
+        uses: ./.github/actions/setup
+        with:
+          download-translations: 'false'
       - name: Bump package versions
         id: bump_package_versions
         shell: bash
+        env:
+          INPUT_VERSION: ${{ github.event.inputs.version }}
         run: |
           declare -A packages=(
             [web]="desktop-client"
             [electron]="desktop-electron"
             [sync]="sync-server"
             [api]="api"
+            [cli]="cli"
+            [core]="loot-core"
           )
+          declare -A new_versions
 
           for key in "${!packages[@]}"; do
             pkg="${packages[$key]}"
 
-            if [[ -n "${{ github.event.inputs.version }}" ]]; then
-              version=$(node ./packages/ci-actions/bin/get-next-package-version.js \
+            if [[ -n "$INPUT_VERSION" ]]; then
+              version=$(yarn workspace @actual-app/ci-actions tsx bin/get-next-package-version.ts \
                 --package-json "./packages/$pkg/package.json" \
-                --version "${{ github.event.inputs.version }}" \
+                --version "$INPUT_VERSION" \
                 --update)
             else
-              version=$(node ./packages/ci-actions/bin/get-next-package-version.js \
+              version=$(yarn workspace @actual-app/ci-actions tsx bin/get-next-package-version.ts \
                 --package-json "./packages/$pkg/package.json" \
                 --type auto \
                 --update)
             fi
 
-            eval "NEW_${key^^}_VERSION=\"$version\""
+            new_versions[$key]="$version"
           done
 
-          echo "version=$NEW_WEB_VERSION" >> "$GITHUB_OUTPUT"
+          echo "version=${new_versions[web]}" >> "$GITHUB_OUTPUT"
       - name: Create PR
-        uses: peter-evans/create-pull-request@271a8d0340265f705b14b6d32b9829c1cb33d45e # v7.0.8
+        uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8.1.0
         with:
           token: ${{ secrets.ACTIONS_UPDATE_TOKEN }}
           commit-message: '🔖 (${{ steps.bump_package_versions.outputs.version }})'
           title: '🔖 (${{ steps.bump_package_versions.outputs.version }})'
           body: 'Generated by [generate-release-pr.yml](../tree/master/.github/workflows/generate-release-pr.yml)'
           branch: 'release/v${{ steps.bump_package_versions.outputs.version }}'
+          base: master

.github/workflows/i18n-string-extract-master.yml

@@ -12,7 +12,7 @@ jobs:
     if: github.repository == 'actualbudget/actual'
     steps:
       - name: Check out main repository
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           path: actual
       - name: Set up environment
@@ -27,12 +27,23 @@ jobs:
       - name: Configure i18n client
         run: |
           pip install wlc
+      - name: Configure Weblate API credentials
+        env:
+          WEBLATE_API_KEY: ${{ secrets.WEBLATE_API_KEY_CI_STRINGS }}
+        run: |
+          # Write the API key to wlc's config file instead of passing it on
+          # the command line, so the secret doesn't appear in process listings.
+          mkdir -p "$HOME/.config"
+          umask 077
+          cat > "$HOME/.config/weblate" <<EOF
+          [keys]
+          https://hosted.weblate.org/api/ = ${WEBLATE_API_KEY}
+          EOF
 
       - name: Lock translations
         run: |
           wlc \
             --url https://hosted.weblate.org/api/ \
-            --key "${{ secrets.WEBLATE_API_KEY_CI_STRINGS }}" \
             lock \
             actualbudget/actual
 
@@ -40,11 +51,10 @@ jobs:
         run: |
           wlc \
             --url https://hosted.weblate.org/api/ \
-            --key "${{ secrets.WEBLATE_API_KEY_CI_STRINGS }}" \
             push \
             actualbudget/actual
       - name: Check out updated translations
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           ssh-key: ${{ secrets.STRING_IMPORT_DEPLOY_KEY }}
           repository: actualbudget/translations
@@ -73,7 +83,6 @@ jobs:
         run: |
           wlc \
             --url https://hosted.weblate.org/api/ \
-            --key "${{ secrets.WEBLATE_API_KEY_CI_STRINGS }}" \
             pull \
             actualbudget/actual
 
@@ -82,6 +91,5 @@ jobs:
         run: |
           wlc \
             --url https://hosted.weblate.org/api/ \
-            --key "${{ secrets.WEBLATE_API_KEY_CI_STRINGS }}" \
             unlock \
             actualbudget/actual

.github/workflows/issues-feature-implemented.yml

@@ -24,8 +24,8 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       # This is not a security concern because we have approved & merged the PR
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
-      - uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
+      - uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
         with:
           node-version: 22
       - name: Handle feature requests

.github/workflows/netlify-release.yml

@@ -21,7 +21,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Repository Checkout
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Set up environment
         uses: ./.github/actions/setup
@@ -34,10 +34,11 @@ jobs:
 
       - name: Deploy to Netlify
         id: netlify_deploy
+        env:
+          NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+          NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_API_TOKEN }}
         run: |
           netlify deploy \
             --dir packages/desktop-client/build \
-            --site ${{ secrets.NETLIFY_SITE_ID }} \
-            --auth ${{ secrets.NETLIFY_API_TOKEN }} \
             --filter @actual-app/web \
             --prod

.github/workflows/publish-flathub.yml

@@ -92,7 +92,7 @@ jobs:
           echo "APPIMAGE_ARM64_SHA256=$APPIMAGE_ARM64_SHA256" >> "$GITHUB_ENV"
 
       - name: Checkout Flathub repo
-        uses: actions/checkout@v6
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           repository: flathub/com.actualbudget.actual
           token: ${{ secrets.FLATHUB_GITHUB_TOKEN }}
@@ -113,7 +113,7 @@ jobs:
           cat com.actualbudget.actual.yml
 
       - name: Create PR in Flathub repo
-        uses: peter-evans/create-pull-request@v7
+        uses: peter-evans/create-pull-request@c0f553fe549906ede9cf27b5156039d195d2ece0 # v8.1.0
         with:
           token: ${{ secrets.FLATHUB_GITHUB_TOKEN }}
           commit-message: 'Update Actual flatpak to version ${{ steps.resolve_version.outputs.version }}'

.github/workflows/publish-nightly-electron.yml

@@ -28,7 +28,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     if: github.event.repository.fork == false
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
       - if: ${{ startsWith(matrix.os, 'windows') }}
         run: pip.exe install setuptools
 
@@ -39,6 +39,9 @@ jobs:
           source .venv/bin/activate
           python3 -m pip install setuptools
 
+      - name: Set up environment
+        uses: ./.github/actions/setup
+
       - if: ${{ startsWith(matrix.os, 'ubuntu') }}
         name: Setup Flatpak dependencies
         run: |
@@ -53,16 +56,14 @@ jobs:
 
           METAINFO_FILE="packages/desktop-electron/extra-resources/linux/com.actualbudget.actual.metainfo.xml"
           TODAY=$(date +%Y-%m-%d)
-          VERSION=$(node ./packages/ci-actions/bin/get-next-package-version.js --package-json ./packages/desktop-electron/package.json --type nightly)
+          VERSION=$(yarn workspace @actual-app/ci-actions tsx bin/get-next-package-version.ts --package-json ./packages/desktop-electron/package.json --type nightly)
           sed -i "s/%RELEASE_VERSION%/$VERSION/g; s/%RELEASE_DATE%/$TODAY/g" "$METAINFO_FILE"
           flatpak run --command=flatpak-builder-lint org.flatpak.Builder appstream "$METAINFO_FILE"
-      - name: Set up environment
-        uses: ./.github/actions/setup
 
       - name: Update package versions
         run: |
           # Get new nightly version
-          NEW_DESKTOP_APP_VERSION=$(node ./packages/ci-actions/bin/get-next-package-version.js --package-json ./packages/desktop-electron/package.json --type nightly)
+          NEW_DESKTOP_APP_VERSION=$(yarn workspace @actual-app/ci-actions tsx bin/get-next-package-version.ts --package-json ./packages/desktop-electron/package.json --type nightly)
 
           # Set package version
           npm version $NEW_DESKTOP_APP_VERSION --no-git-tag-version --workspace=desktop-electron --no-workspaces-update
@@ -82,49 +83,49 @@ jobs:
         run: ./bin/package-electron
 
       - name: Upload Linux x64 AppImage
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: Actual-linux-x86_64.AppImage
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-linux-x86_64.AppImage
 
       - name: Upload Linux arm64 AppImage
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: Actual-linux-arm64.AppImage
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-linux-arm64.AppImage
 
       - name: Upload Windows x32 exe
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: Actual-windows-ia32.exe
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-windows-ia32.exe
 
       - name: Upload Windows x64 exe
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: Actual-windows-x64.exe
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-windows-x64.exe
 
       - name: Upload Windows arm64 exe
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: Actual-windows-arm64.exe
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-windows-arm64.exe
 
       - name: Upload Mac x64 dmg
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: Actual-mac-x64.dmg
           if-no-files-found: ignore
           path: packages/desktop-electron/dist/Actual-mac-x64.dmg
 
       - name: Upload Mac arm64 dmg
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: Actual-mac-arm64.dmg
           if-no-files-found: ignore
@@ -132,7 +133,7 @@ jobs:
 
       - name: Upload Windows Store Build
         if: ${{ startsWith(matrix.os, 'windows') }}
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: actual-electron-${{ matrix.os }}-appx
           path: |

.github/workflows/publish-nightly-npm-packages.yml

@@ -12,7 +12,7 @@ jobs:
     name: Build and pack npm packages
     if: github.event.repository.fork == false
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Set up environment
         uses: ./.github/actions/setup
@@ -20,19 +20,27 @@ jobs:
       - name: Update package versions
         run: |
           # Get new nightly versions
-          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_CORE_VERSION=$(yarn workspace @actual-app/ci-actions tsx bin/get-next-package-version.ts --package-json ./packages/loot-core/package.json --type nightly)
+          NEW_WEB_VERSION=$(yarn workspace @actual-app/ci-actions tsx bin/get-next-package-version.ts --package-json ./packages/desktop-client/package.json --type nightly)
+          NEW_SYNC_VERSION=$(yarn workspace @actual-app/ci-actions tsx bin/get-next-package-version.ts --package-json ./packages/sync-server/package.json --type nightly)
+          NEW_API_VERSION=$(yarn workspace @actual-app/ci-actions tsx bin/get-next-package-version.ts --package-json ./packages/api/package.json --type nightly)
+          NEW_CLI_VERSION=$(yarn workspace @actual-app/ci-actions tsx bin/get-next-package-version.ts --package-json ./packages/cli/package.json --type nightly)
 
           # Set package versions
+          npm version $NEW_CORE_VERSION --no-git-tag-version --workspace=@actual-app/core --no-workspaces-update
           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: |
           yarn install
 
+      - name: Pack the core package
+        run: |
+          yarn workspace @actual-app/core pack --filename @actual-app/core.tgz
+
       - name: Build Server & Web
         run: yarn build:server
 
@@ -48,14 +56,23 @@ 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
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: npm-packages
           path: |
+            packages/loot-core/@actual-app/core.tgz
             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
@@ -66,16 +83,22 @@ jobs:
       packages: write
     steps:
       - name: Download the artifacts
-        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: npm-packages
 
       - name: Setup node and npm registry
-        uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
         with:
           node-version: 22
           registry-url: 'https://registry.npmjs.org'
 
+      - name: Publish Core
+        run: |
+          npm publish loot-core/@actual-app/core.tgz --access public --tag nightly
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
       - name: Publish Web
         run: |
           npm publish desktop-client/@actual-app/web.tgz --access public --tag nightly
@@ -93,3 +116,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 }}

.github/workflows/publish-npm-packages.yml

@@ -11,11 +11,15 @@ jobs:
     runs-on: ubuntu-latest
     name: Build and pack npm packages
     steps:
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
 
       - name: Set up environment
         uses: ./.github/actions/setup
 
+      - name: Pack the core package
+        run: |
+          yarn workspace @actual-app/core pack --filename @actual-app/core.tgz
+
       - name: Build Web
         run: yarn build:server
 
@@ -31,14 +35,23 @@ 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
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: npm-packages
           path: |
+            packages/loot-core/@actual-app/core.tgz
             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
@@ -49,16 +62,22 @@ jobs:
       packages: write
     steps:
       - name: Download the artifacts
-        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           name: npm-packages
 
       - name: Setup node and npm registry
-        uses: actions/setup-node@2028fbc5c25fe9cf00d9f06a71cc4710d4507903 # v6.0.0
+        uses: actions/setup-node@53b83947a5a98c8d113130e565377fae1a50d02f # v6.3.0
         with:
           node-version: 22
           registry-url: 'https://registry.npmjs.org'
 
+      - name: Publish Core
+        run: |
+          npm publish loot-core/@actual-app/core.tgz --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
       - name: Publish Web
         run: |
           npm publish desktop-client/@actual-app/web.tgz --access public
@@ -76,3 +95,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 }}

.github/workflows/release-notes.yml

@@ -12,7 +12,7 @@ jobs:
     runs-on: ubuntu-latest
     steps:
       - name: Checkout
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           fetch-depth: 0
       - name: Get changed files
@@ -30,7 +30,7 @@ jobs:
           fi
       - name: Check release notes
         if: startsWith(github.head_ref, 'release/') == false && steps.changed-files.outputs.only_docs != 'true'
-        uses: actualbudget/actions/release-notes/check@main
+        uses: ./.github/actions/release-notes/check
       - name: Generate release notes
         if: startsWith(github.head_ref, 'release/') == true
-        uses: actualbudget/actions/release-notes/generate@main
+        uses: ./.github/actions/release-notes/generate

.github/workflows/size-compare.yml

@@ -35,7 +35,7 @@ jobs:
       contents: read
     steps:
       - name: Checkout base branch
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           ref: ${{ github.base_ref }}
       - name: Set up environment
@@ -57,6 +57,13 @@ jobs:
           token: ${{ secrets.GITHUB_TOKEN }}
           checkName: api
           ref: ${{github.base_ref}}
+      - name: Wait for ${{github.base_ref}} CLI build to succeed
+        uses: fountainhead/action-wait-for-check@5a908a24814494009c4bb27c242ea38c93c593be # v1.2.0
+        id: master-cli-build
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          checkName: cli
+          ref: ${{github.base_ref}}
 
       - name: Wait for PR build to succeed
         uses: fountainhead/action-wait-for-check@5a908a24814494009c4bb27c242ea38c93c593be # v1.2.0
@@ -72,15 +79,22 @@ jobs:
           token: ${{ secrets.GITHUB_TOKEN }}
           checkName: api
           ref: ${{github.event.pull_request.head.sha}}
+      - name: Wait for CLI PR build to succeed
+        uses: fountainhead/action-wait-for-check@5a908a24814494009c4bb27c242ea38c93c593be # v1.2.0
+        id: wait-for-cli-build
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          checkName: cli
+          ref: ${{github.event.pull_request.head.sha}}
 
       - name: Report build failure
-        if: steps.wait-for-web-build.outputs.conclusion == 'failure' || steps.wait-for-api-build.outputs.conclusion == 'failure'
+        if: steps.wait-for-web-build.outputs.conclusion == 'failure' || steps.wait-for-api-build.outputs.conclusion == 'failure' || steps.wait-for-cli-build.outputs.conclusion == 'failure'
         run: |
           echo "Build failed on PR branch or ${{github.base_ref}}"
           exit 1
 
       - name: Download web build artifact from ${{github.base_ref}}
-        uses: dawidd6/action-download-artifact@ac66b43f0e6a346234dd65d4d0c8fbb31cb316e5 # v11
+        uses: dawidd6/action-download-artifact@1f8785ff7a5130826f848e7f72725c85d241860f # v18
         id: pr-web-build
         with:
           branch: ${{github.base_ref}}
@@ -89,7 +103,7 @@ jobs:
           name: build-stats
           path: base
       - name: Download API build artifact from ${{github.base_ref}}
-        uses: dawidd6/action-download-artifact@ac66b43f0e6a346234dd65d4d0c8fbb31cb316e5 # v11
+        uses: dawidd6/action-download-artifact@1f8785ff7a5130826f848e7f72725c85d241860f # v18
         id: pr-api-build
         with:
           branch: ${{github.base_ref}}
@@ -98,7 +112,7 @@ jobs:
           name: api-build-stats
           path: base
       - name: Download build stats from PR
-        uses: dawidd6/action-download-artifact@ac66b43f0e6a346234dd65d4d0c8fbb31cb316e5 # v11
+        uses: dawidd6/action-download-artifact@1f8785ff7a5130826f848e7f72725c85d241860f # v18
         with:
           pr: ${{github.event.pull_request.number}}
           workflow: build.yml
@@ -107,7 +121,7 @@ jobs:
           path: head
           allow_forks: true
       - name: Download API stats from PR
-        uses: dawidd6/action-download-artifact@ac66b43f0e6a346234dd65d4d0c8fbb31cb316e5 # v11
+        uses: dawidd6/action-download-artifact@1f8785ff7a5130826f848e7f72725c85d241860f # v18
         with:
           pr: ${{github.event.pull_request.number}}
           workflow: build.yml
@@ -115,6 +129,23 @@ jobs:
           name: api-build-stats
           path: head
           allow_forks: true
+      - name: Download CLI build artifact from ${{github.base_ref}}
+        uses: dawidd6/action-download-artifact@1f8785ff7a5130826f848e7f72725c85d241860f # v18
+        with:
+          branch: ${{github.base_ref}}
+          workflow: build.yml
+          workflow_conclusion: '' # ignore the conclusion of the workflow, since we already checked it
+          name: cli-build-stats
+          path: base
+      - name: Download CLI stats from PR
+        uses: dawidd6/action-download-artifact@1f8785ff7a5130826f848e7f72725c85d241860f # v18
+        with:
+          pr: ${{github.event.pull_request.number}}
+          workflow: build.yml
+          workflow_conclusion: '' # ignore the conclusion of the workflow, since we already checked it
+          name: cli-build-stats
+          path: head
+          allow_forks: true
       - name: Strip content hashes from stats files
         run: |
           if [ -f ./head/web-stats.json ]; then
@@ -136,9 +167,11 @@ jobs:
             --base desktop-client=./base/web-stats.json \
             --base loot-core=./base/loot-core-stats.json \
             --base api=./base/api-stats.json \
+            --base cli=./base/cli-stats.json \
             --head desktop-client=./head/web-stats.json \
             --head loot-core=./head/loot-core-stats.json \
             --head api=./head/api-stats.json \
+            --head cli=./head/cli-stats.json \
             --identifier combined \
             --format pr-body > bundle-stats-comment.md
       - name: Post combined bundle stats comment

.github/workflows/stale.yml

@@ -8,7 +8,7 @@ jobs:
   stale:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/stale@5f858e3efba33a5ca4407a664cc011ad407f2008 # v10.1.0
+      - uses: actions/stale@b5d41d4e1d5dceea10e7104786b73624c18a190f # v10.2.0
         with:
           stale-pr-message: 'This PR is stale because it has been open 30 days with no activity. Remove stale label or comment or this will be closed in 5 days.'
           close-pr-message: 'This PR was closed because it has been stalled for 5 days with no activity.'
@@ -18,7 +18,7 @@ jobs:
   stale-wip:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/stale@5f858e3efba33a5ca4407a664cc011ad407f2008 # v10.1.0
+      - uses: actions/stale@b5d41d4e1d5dceea10e7104786b73624c18a190f # v10.2.0
         with:
           stale-pr-message: ':wave: Hi! It looks like this PR has not had any changes for a week now. Would you like someone to review this PR? If so - please remove the "[WIP]" prefix from the PR title. That will let the community know that this PR is open for a review.'
           days-before-stale: 7
@@ -29,7 +29,7 @@ jobs:
   stale-needs-info:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/stale@5f858e3efba33a5ca4407a664cc011ad407f2008 # v10.1.0
+      - uses: actions/stale@b5d41d4e1d5dceea10e7104786b73624c18a190f # v10.2.0
         with:
           stale-issue-label: 'needs info'
           days-before-stale: -1

.github/workflows/vrt-update-apply.yml

@@ -19,7 +19,7 @@ jobs:
     if: ${{ github.event.workflow_run.conclusion == 'success' }}
     steps:
       - name: Download patch artifact
-        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           run-id: ${{ github.event.workflow_run.id }}
@@ -27,7 +27,7 @@ jobs:
           path: /tmp/artifacts
 
       - name: Download metadata artifact
-        uses: actions/download-artifact@018cc2cf5baa6db3ef3c5f8a56943fffe632ef53 # v6.0.0
+        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
           github-token: ${{ secrets.GITHUB_TOKEN }}
           run-id: ${{ github.event.workflow_run.id }}
@@ -54,7 +54,7 @@ jobs:
 
       - name: Checkout fork branch
         if: steps.metadata.outputs.pr_number != ''
-        uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+        uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           repository: ${{ steps.metadata.outputs.head_repo }}
           ref: ${{ steps.metadata.outputs.head_ref }}
@@ -134,11 +134,14 @@ jobs:
       - name: Comment on PR - Failure
         if: failure() && steps.metadata.outputs.pr_number != ''
         uses: actions/github-script@ed597411d8f924073f98dfc5c65a23a2325f34cd # v8.0.0
+        env:
+          APPLY_ERROR: ${{ steps.apply.outputs.error }}
+          PR_NUMBER: ${{ steps.metadata.outputs.pr_number }}
         with:
           script: |
-            const error = `${{ steps.apply.outputs.error }}` || 'Unknown error occurred';
+            const error = process.env.APPLY_ERROR || 'Unknown error occurred';
             await github.rest.issues.createComment({
-              issue_number: ${{ steps.metadata.outputs.pr_number }},
+              issue_number: parseInt(process.env.PR_NUMBER, 10),
               owner: context.repo.owner,
               repo: context.repo.repo,
               body: `❌ Failed to apply VRT updates: ${error}\n\nPlease check the workflow logs for details.`

.github/workflows/vrt-update-generate.yml

@@ -60,7 +60,7 @@ jobs:
             core.setOutput('head_ref', pr.head.ref);
             core.setOutput('head_repo', pr.head.repo.full_name);
 
-      - uses: actions/checkout@08c6903cd8c0fde910a37f88322edcfb5dd907a8 # v5.0.0
+      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd # v6.0.2
         with:
           ref: ${{ steps.pr.outputs.head_sha }}
 
@@ -113,7 +113,7 @@ jobs:
 
       - name: Upload patch artifact
         if: steps.create-patch.outputs.has_changes == 'true'
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: vrt-patch-${{ github.event.issue.number }}
           path: vrt-update.patch
@@ -129,7 +129,7 @@ jobs:
 
       - name: Upload PR metadata
         if: steps.create-patch.outputs.has_changes == 'true'
-        uses: actions/upload-artifact@330a01c490aca151604b8cf639adc76d48f6c5d4 # v5.0.0
+        uses: actions/upload-artifact@bbbca2ddaa5d8feaa63e36b76fdaad77386f024f # v7.0.0
         with:
           name: vrt-metadata-${{ github.event.issue.number }}
           path: pr-metadata/

.gitignore

@@ -58,6 +58,10 @@ bundle.mobile.js.map
 # IntelliJ IDEA
 .idea
 
+# Claude Code
+.claude/worktrees/*
+.claude/settings.local.json
+
 # Misc
 .#*
 
@@ -81,3 +85,10 @@ build/
 
 *storybook.log
 storybook-static
+
+# cli config when testing locally
+.actualrc.json
+.actualrc
+.actualrc.yaml
+.actualrc.yml
+actual.config.js

.husky/post-checkout

@@ -0,0 +1,21 @@
+#!/bin/sh
+# Run yarn install when switching branches (if yarn.lock changed)
+# or when creating a new worktree (node_modules won't exist yet)
+
+# $3 is 1 for branch checkout, 0 for file checkout
+if [ "$3" != "1" ]; then
+  exit 0
+fi
+
+# Worktree creation: node_modules doesn't exist yet, always install
+if [ ! -d "node_modules" ]; then
+  echo "New worktree detected — running yarn install..."
+  yarn install || exit 1
+  exit 0
+fi
+
+# Check if yarn.lock changed between the old and new HEAD
+if git diff --name-only "$1" "$2" | grep -q "^yarn.lock$"; then
+  echo "yarn.lock changed — running yarn install..."
+  yarn install
+fi

.husky/post-merge

@@ -0,0 +1,7 @@
+#!/bin/sh
+# Run yarn install after pulling/merging (if yarn.lock changed)
+
+if git diff --name-only ORIG_HEAD HEAD | grep -q "^yarn.lock$"; then
+  echo "yarn.lock changed — running yarn install..."
+  yarn install
+fi

.oxfmtrc.json

@@ -9,24 +9,14 @@
       "react",
       "builtin",
       "external",
-      "loot-core",
-      "parent",
+      ["parent", "subpath"],
       "sibling",
-      "index",
-      "desktop-client"
+      "index"
     ],
     "customGroups": [
       {
         "groupName": "react",
         "elementNamePattern": ["react", "react-dom/*", "react-*"]
-      },
-      {
-        "groupName": "loot-core",
-        "elementNamePattern": ["loot-core/**"]
-      },
-      {
-        "groupName": "desktop-client",
-        "elementNamePattern": ["@desktop-client/**"]
       }
     ],
     "newlinesBetween": true

.oxlintrc.json

@@ -36,6 +36,7 @@
     "actual/prefer-const": "error",
     "actual/no-anchor-tag": "error",
     "actual/no-react-default-import": "error",
+    "actual/prefer-subpath-imports": "error",
 
     // JSX A11y rules
     "jsx-a11y/no-autofocus": [
@@ -101,8 +102,18 @@
     "typescript/no-var-requires": "error",
     // we want to allow unions such as "{ name: DbAccount['name'] | DbPayee['name'] }"
     "typescript/no-duplicate-type-constituents": "off",
+    // we want to allow unions such as "string | 'network' | 'file-key-mismatch'"
+    "typescript/no-redundant-type-constituents": "off",
     "typescript/await-thenable": "error",
-    "typescript/no-floating-promises": "warn", // TODO: covert to error
+    "typescript/no-floating-promises": "error",
+    "typescript/require-array-sort-compare": "error",
+    "typescript/unbound-method": "error",
+    "typescript/no-for-in-array": "error",
+    "typescript/restrict-template-expressions": "error",
+    "typescript/no-misused-spread": "warn", // TODO: enable this
+    "typescript/no-base-to-string": "warn", // TODO: enable this
+    "typescript/no-unsafe-unary-minus": "warn", // TODO: enable this
+    "typescript/no-unsafe-type-assertion": "warn", // TODO: enable this
 
     // Import rules
     "import/consistent-type-specifier-style": "error",
@@ -325,7 +336,7 @@
         ],
         "patterns": [
           {
-            "group": ["**/*.api", "**/*.web", "**/*.electron"],
+            "group": ["**/*.api", "**/*.electron"],
             "message": "Don't directly reference imports from other platforms"
           },
           {
@@ -351,7 +362,9 @@
     ],
     "eslint/no-useless-constructor": "error",
     "eslint/no-undef": "error",
-    "eslint/no-unused-expressions": "error"
+    "eslint/no-unused-expressions": "error",
+    "eslint/no-return-assign": "error",
+    "eslint/no-unused-vars": "error"
   },
   "overrides": [
     {

AGENTS.md

@@ -44,25 +44,9 @@ yarn start:desktop
 
 ### ⚠️ CRITICAL REQUIREMENT: AI-Generated Commit Messages and PR Titles
 
-**THIS IS A MANDATORY REQUIREMENT THAT MUST BE FOLLOWED WITHOUT EXCEPTION:**
+**ALL commit messages and PR titles MUST be prefixed with `[AI]`.** No exceptions.
 
-- **ALL commit messages MUST be prefixed with `[AI]`**
-- **ALL pull request titles MUST be prefixed with `[AI]`**
-
-**Examples:**
-
-- ✅ `[AI] Fix type error in account validation`
-- ✅ `[AI] Add support for new transaction categories`
-- ❌ `Fix type error in account validation` (MISSING PREFIX - NOT ALLOWED)
-- ❌ `Add support for new transaction categories` (MISSING PREFIX - NOT ALLOWED)
-
-**This requirement applies to:**
-
-- Every single commit message created by AI agents
-- Every single pull request title created by AI agents
-- No exceptions are permitted
-
-**This is a hard requirement that agents MUST follow. Failure to include the `[AI]` prefix is a violation of these instructions.**
+See [PR and Commit Rules](.github/agents/pr-and-commit-rules.md) for the full specification, including git safety rules, pre-commit checklist, and PR workflow.
 
 ### Task Orchestration with Lage
 
@@ -100,7 +84,7 @@ The core application logic that runs on any platform.
 
   ```bash
   # Run all loot-core tests
-  yarn workspace loot-core run test
+  yarn workspace @actual-app/core run test
 
   # Or run tests across all packages using lage
   yarn test
@@ -235,7 +219,7 @@ yarn test
 yarn test:debug
 
 # Run tests for a specific package
-yarn workspace loot-core run test
+yarn workspace @actual-app/core run test
 ```
 
 **E2E Tests (Playwright)**
@@ -347,7 +331,7 @@ Always maintain newlines between import groups.
 
 ### Platform-Specific Code
 
-- Don't directly reference platform-specific imports (`.api`, `.web`, `.electron`)
+- Don't directly reference platform-specific imports (`.api`, `.electron`)
 - Use conditional exports in `loot-core` for platform-specific code
 - Platform resolution happens at build time via package.json exports
 
@@ -361,13 +345,7 @@ Always maintain newlines between import groups.
 
 **Git Commands:**
 
-- **MANDATORY: ALL commit messages MUST be prefixed with `[AI]`** - This is a hard requirement with no exceptions
-- **MANDATORY: ALL pull request titles MUST be prefixed with `[AI]`** - This is a hard requirement with no exceptions
-- Never update git config
-- Never run destructive git operations (force push, hard reset) unless explicitly requested
-- Never skip hooks (--no-verify, --no-gpg-sign)
-- Never force push to main/master
-- Never commit unless explicitly asked
+See [PR and Commit Rules](.github/agents/pr-and-commit-rules.md) for complete git safety rules, commit message requirements, and PR workflow.
 
 ## File Structure Patterns
 
@@ -523,7 +501,7 @@ Icons in `packages/component-library/src/icons/` are auto-generated. Don't manua
 
 1. Check `tsconfig.json` for path mappings
 2. Check package.json `exports` field (especially for loot-core)
-3. Verify platform-specific imports (`.web`, `.electron`, `.api`)
+3. Verify platform-specific imports (`.electron`, `.api`)
 4. Use absolute imports in `desktop-client` (enforced by ESLint)
 
 ### Build Failures
@@ -566,7 +544,7 @@ Icons in `packages/component-library/src/icons/` are auto-generated. Don't manua
 
 Before committing changes, ensure:
 
-- [ ] **MANDATORY: Commit message is prefixed with `[AI]`** - This is a hard requirement with no exceptions
+- [ ] Commit and PR rules followed (see [PR and Commit Rules](.github/agents/pr-and-commit-rules.md))
 - [ ] `yarn typecheck` passes
 - [ ] `yarn lint:fix` has been run
 - [ ] Relevant tests pass
@@ -579,17 +557,7 @@ Before committing changes, ensure:
 
 ## Pull Request Guidelines
 
-When creating pull requests:
-
-- **MANDATORY PREFIX REQUIREMENT**: **ALL pull request titles MUST be prefixed with `[AI]`** - This is a hard requirement that MUST be followed without exception
-  - ✅ Correct: `[AI] Fix type error in account validation`
-  - ❌ Incorrect: `Fix type error in account validation` (MISSING PREFIX - NOT ALLOWED)
-- **AI-Generated PRs**: If you create a PR using AI assistance, add the **"AI generated"** label to the pull request. This helps maintainers understand the nature of the contribution.
-
-### PR Template: Do Not Fill In
-
-- **NEVER fill in the PR template** (`.github/PULL_REQUEST_TEMPLATE.md`). Leave all blank spaces and placeholder comments as-is. We expect **humans** to fill in the Description, Related issue(s), Testing, and Checklist sections.
-- **Exception**: If a human **explicitly asks** you to fill out the PR template, then fill it out **in Chinese**, using Chinese characters (简体中文) for all content you add.
+See [PR and Commit Rules](.github/agents/pr-and-commit-rules.md) for complete PR creation rules, including title prefix requirements, labeling, and PR template handling.
 
 ## Code Review Guidelines
 
@@ -657,7 +625,7 @@ Standard commands documented in `package.json` scripts and the Quick Start secti
 
 - `yarn lint` / `yarn lint:fix` (uses oxlint + oxfmt)
 - `yarn test` (lage across all workspaces)
-- `yarn typecheck` (tsc + lage typecheck)
+- `yarn typecheck` (tsgo + lage typecheck)
 
 ### Testing and previewing the app
 

CLAUDE.md

@@ -1 +1,2 @@
 @AGENTS.md
+@.github/agents/pr-and-commit-rules.md

bin/package-browser

@@ -17,7 +17,7 @@ packages/desktop-client/bin/remove-untranslated-languages
 export NODE_OPTIONS="--max-old-space-size=4096"
 
 yarn workspace plugins-service build
-yarn workspace loot-core build:browser
+yarn workspace @actual-app/core build:browser
 yarn workspace @actual-app/web build:browser
 
 echo "packages/desktop-client/build"

bin/package-electron

@@ -43,6 +43,7 @@ if [ $SKIP_TRANSLATIONS == false ]; then
 
   pushd packages/desktop-client/locale > /dev/null
 
+  git checkout .
   git pull
   popd > /dev/null
   packages/desktop-client/bin/remove-untranslated-languages
@@ -51,16 +52,16 @@ fi
 export NODE_OPTIONS="--max-old-space-size=4096"
 
 yarn workspace plugins-service build
-yarn workspace loot-core build:node
+yarn workspace @actual-app/core build:node
 yarn workspace @actual-app/web build --mode=desktop # electron specific build
 
 # required for running the sync-server server
-yarn workspace loot-core build:browser
+yarn workspace @actual-app/core build:browser
 yarn workspace @actual-app/web build:browser
 yarn workspace @actual-app/sync-server build
 
-# Emit loot-core declarations so desktop-electron (which includes typings/window.ts) can build
-yarn workspace loot-core exec tsc -p tsconfig.json
+# Emit @actual-app/core declarations so desktop-electron (which includes typings/window.ts) can build
+yarn workspace @actual-app/core exec tsgo -p tsconfig.json
 
 yarn workspace desktop-electron update-client
 

lage.config.js

@@ -3,6 +3,7 @@ module.exports = {
   pipeline: {
     typecheck: {
       type: 'npmScript',
+      dependsOn: ['^typecheck'],
     },
     test: {
       type: 'npmScript',
@@ -16,6 +17,7 @@ module.exports = {
     },
     build: {
       type: 'npmScript',
+      dependsOn: ['^build'],
       cache: true,
       options: {
         outputGlob: ['lib-dist/**', 'dist/**', 'build/**'],

package.json

@@ -25,21 +25,23 @@
     "start:desktop": "yarn desktop-dependencies && npm-run-all --parallel 'start:desktop-*'",
     "start:docs": "yarn workspace docs start",
     "desktop-dependencies": "npm-run-all --parallel rebuild-electron build:browser-backend build:plugins-service",
-    "start:desktop-node": "yarn workspace loot-core watch:node",
+    "start:desktop-node": "yarn workspace @actual-app/core watch:node",
     "start:desktop-client": "yarn workspace @actual-app/web watch",
     "start:desktop-server-client": "yarn workspace @actual-app/web build:browser",
     "start:desktop-electron": "yarn workspace desktop-electron watch",
     "start:browser": "yarn workspace plugins-service build-dev && npm-run-all --parallel 'start:browser-*'",
     "start:service-plugins": "yarn workspace plugins-service watch",
-    "start:browser-backend": "yarn workspace loot-core watch:browser",
+    "start:browser-backend": "yarn workspace @actual-app/core watch:browser",
     "start:browser-frontend": "yarn workspace @actual-app/web start:browser",
     "start:storybook": "yarn workspace @actual-app/components start:storybook",
-    "build:browser-backend": "yarn workspace loot-core build:browser",
+    "build": "lage build",
+    "build:browser-backend": "yarn workspace @actual-app/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",
@@ -53,40 +55,46 @@
     "vrt": "yarn workspace @actual-app/web run vrt",
     "vrt:docker": "./bin/run-vrt",
     "rebuild-electron": "./node_modules/.bin/electron-rebuild -m ./packages/loot-core",
-    "rebuild-node": "yarn workspace loot-core rebuild",
-    "lint": "yarn workspace @actual-app/api clean && oxfmt --check . && oxlint --type-aware",
-    "lint:fix": "yarn workspace @actual-app/api clean && oxfmt . && oxlint --fix --type-aware",
+    "rebuild-node": "yarn workspace @actual-app/core rebuild",
+    "lint": "oxfmt --check . && oxlint --type-aware --quiet",
+    "lint:fix": "oxfmt . && oxlint --fix --type-aware --quiet",
     "install:server": "yarn workspaces focus @actual-app/sync-server --production",
-    "typecheck": "yarn workspace @actual-app/api clean && tsc -b && tsc -p tsconfig.root.json --noEmit && lage typecheck",
-    "jq": "./node_modules/node-jq/bin/jq",
+    "constraints": "yarn constraints",
+    "typecheck": "tsgo -p tsconfig.root.json --noEmit && lage typecheck",
     "prepare": "husky"
   },
   "devDependencies": {
     "@octokit/rest": "^22.0.1",
-    "@types/node": "^22.19.10",
+    "@types/node": "^22.19.15",
     "@types/prompts": "^2.4.9",
-    "baseline-browser-mapping": "^2.9.19",
+    "@typescript/native-preview": "^7.0.0-dev.20260309.1",
+    "@yarnpkg/types": "^4.0.1",
     "cross-env": "^10.1.0",
-    "eslint": "^9.39.2",
-    "eslint-plugin-perfectionist": "^4.15.1",
+    "eslint": "^9.39.3",
+    "eslint-plugin-perfectionist": "^5.6.0",
     "eslint-plugin-typescript-paths": "^0.0.33",
     "html-to-image": "^1.11.13",
     "husky": "^9.1.7",
-    "lage": "^2.14.17",
-    "lint-staged": "^16.2.7",
-    "minimatch": "^10.1.2",
-    "node-jq": "^6.3.1",
+    "lage": "^2.14.19",
+    "lint-staged": "^16.3.2",
+    "minimatch": "^10.2.4",
     "npm-run-all": "^4.1.5",
     "oxfmt": "^0.32.0",
-    "oxlint": "^1.47.0",
+    "oxlint": "^1.51.0",
     "oxlint-tsgolint": "^0.13.0",
     "p-limit": "^7.3.0",
     "prompts": "^2.4.2",
-    "source-map-support": "^0.5.21",
     "ts-node": "^10.9.2",
     "typescript": "^5.9.3"
   },
   "resolutions": {
+    "adm-zip": "patch:adm-zip@npm%3A0.5.16#~/.yarn/patches/adm-zip-npm-0.5.16-4556fea098.patch",
+    "minimatch@10.2.1": "10.2.5",
+    "minimatch@3.1.2": "3.1.5",
+    "minimatch@>=10.0.0 <11.0.0": "10.2.5",
+    "minimatch@>=3.0.0 <4.0.0": "3.1.5",
+    "minimatch@>=5.0.0 <6.0.0": "5.1.9",
+    "minimatch@>=9.0.0 <10.0.0": "9.0.9",
     "rollup": "4.40.1",
     "socks": ">=2.8.3"
   },
@@ -95,7 +103,7 @@
       "oxfmt --no-error-on-unmatched-pattern"
     ],
     "*.{js,mjs,jsx,ts,tsx}": [
-      "oxlint --fix --type-aware"
+      "oxlint --fix --type-aware --quiet"
     ]
   },
   "browserslist": [

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 || [],

packages/api/index.ts

@@ -1,53 +1,30 @@
-import type {
-  RequestInfo as FetchInfo,
-  RequestInit as FetchInit,
-} from 'node-fetch';
+import { init as initLootCore } from '@actual-app/core/server/main';
+import type { InitConfig, lib } from '@actual-app/core/server/main';
 
-// loot-core types
-import type { InitConfig } from 'loot-core/server/main';
-
-// oxlint-disable-next-line typescript/ban-ts-comment
-// @ts-ignore: bundle not available until we build it
-import * as bundle from './app/bundle.api.js';
-import * as injected from './injected';
 import { validateNodeVersion } from './validateNodeVersion';
 
-let actualApp: null | typeof bundle.lib;
-export const internal = bundle.lib;
-
 export * from './methods';
 export * as utils from './utils';
 
-export async function init(config: InitConfig = {}) {
-  if (actualApp) {
-    return;
-  }
+/** @deprecated Please use return value of `init` instead */
+export let internal: typeof lib | null = null;
 
+export async function init(config: InitConfig = {}) {
   validateNodeVersion();
 
-  if (!globalThis.fetch) {
-    globalThis.fetch = (url: URL | RequestInfo, init?: RequestInit) => {
-      return import('node-fetch').then(({ default: fetch }) =>
-        fetch(url as unknown as FetchInfo, init as unknown as FetchInit),
-      ) as unknown as Promise<Response>;
-    };
-  }
-
-  await bundle.init(config);
-  actualApp = bundle.lib;
-
-  injected.override(bundle.lib.send);
-  return bundle.lib;
+  internal = await initLootCore(config);
+  return internal;
 }
 
 export async function shutdown() {
-  if (actualApp) {
+  if (internal) {
     try {
-      await actualApp.send('sync');
+      await internal.send('sync');
     } catch {
       // most likely that no budget is loaded, so the sync failed
     }
-    await actualApp.send('close-budget');
-    actualApp = null;
+
+    await internal.send('close-budget');
+    internal = null;
   }
 }

packages/api/injected.js

@@ -1,7 +0,0 @@
-// TODO: comment on why it works this way
-
-export let send;
-
-export function override(sendImplementation) {
-  send = sendImplementation;
-}

packages/api/methods.test.ts

@@ -1,10 +1,28 @@
 import * as fs from 'fs/promises';
 import * as path from 'path';
 
-import type { RuleEntity } from 'loot-core/types/models';
+import type { RuleEntity } from '@actual-app/core/types/models';
+import { vi } from 'vitest';
 
 import * as api from './index';
 
+// In tests we run from source; loot-core's API fs uses __dirname (for the built dist/).
+// Mock the fs so path constants point at loot-core package root where migrations live.
+vi.mock(
+  '../loot-core/src/platform/server/fs/index.api',
+  async importOriginal => {
+    const actual = (await importOriginal()) as Record<string, unknown>;
+    const pathMod = await import('path');
+    const lootCoreRoot = pathMod.join(__dirname, '..', 'loot-core');
+    return {
+      ...actual,
+      migrationsPath: pathMod.join(lootCoreRoot, 'migrations'),
+      bundledDatabasePath: pathMod.join(lootCoreRoot, 'default-db.sqlite'),
+      demoBudgetPath: pathMod.join(lootCoreRoot, 'demo-budget'),
+    };
+  },
+);
+
 const budgetName = 'test-budget';
 
 global.IS_TESTING = true;
@@ -877,6 +895,73 @@ describe('API CRUD operations', () => {
     );
     expect(transactions[0].notes).toBeNull();
   });
+
+  test('Transactions: reimportDeleted=false prevents reimporting deleted transactions', async () => {
+    const accountId = await api.createAccount({ name: 'test-account' }, 0);
+
+    // Import a transaction
+    const result1 = await api.importTransactions(accountId, [
+      {
+        date: '2023-11-03',
+        imported_id: 'reimport-test-1',
+        amount: 100,
+        account: accountId,
+      },
+    ]);
+    expect(result1.added).toHaveLength(1);
+
+    // Delete the transaction
+    await api.deleteTransaction(result1.added[0]);
+
+    // Reimport the same transaction with reimportDeleted=false
+    const result2 = await api.importTransactions(
+      accountId,
+      [
+        {
+          date: '2023-11-03',
+          imported_id: 'reimport-test-1',
+          amount: 100,
+          account: accountId,
+        },
+      ],
+      { reimportDeleted: false },
+    );
+
+    // Should match the deleted transaction and not create a new one
+    expect(result2.added).toHaveLength(0);
+    expect(result2.updated).toHaveLength(0);
+  });
+
+  test('Transactions: reimportDeleted=true reimports deleted transactions', async () => {
+    const accountId = await api.createAccount({ name: 'test-account' }, 0);
+
+    // Import a transaction
+    const result1 = await api.importTransactions(accountId, [
+      {
+        date: '2023-11-03',
+        imported_id: 'reimport-test-2',
+        amount: 200,
+        account: accountId,
+      },
+    ]);
+    expect(result1.added).toHaveLength(1);
+
+    // Delete the transaction
+    await api.deleteTransaction(result1.added[0]);
+
+    // Reimport the same transaction relying on reimportDeleted=true default
+    const result2 = await api.importTransactions(accountId, [
+      {
+        date: '2023-11-03',
+        imported_id: 'reimport-test-2',
+        amount: 200,
+        account: accountId,
+      },
+    ]);
+
+    // Should create a new transaction since deleted ones are ignored
+    expect(result2.added).toHaveLength(1);
+  });
 });
 
 //apis: createSchedule, getSchedules, updateSchedule, deleteSchedule

packages/api/methods.ts

@@ -6,17 +6,16 @@ import type {
   APIPayeeEntity,
   APIScheduleEntity,
   APITagEntity,
-} from 'loot-core/server/api-models';
-import type { Query } from 'loot-core/shared/query';
-import type { ImportTransactionsOpts } from 'loot-core/types/api-handlers';
-import type { Handlers } from 'loot-core/types/handlers';
+} from '@actual-app/core/server/api-models';
+import { lib } from '@actual-app/core/server/main';
+import type { Query } from '@actual-app/core/shared/query';
+import type { ImportTransactionsOpts } from '@actual-app/core/types/api-handlers';
+import type { Handlers } from '@actual-app/core/types/handlers';
 import type {
   ImportTransactionEntity,
   RuleEntity,
   TransactionEntity,
-} from 'loot-core/types/models';
-
-import * as injected from './injected';
+} from '@actual-app/core/types/models';
 
 export { q } from './app/query';
 
@@ -24,7 +23,7 @@ function send<K extends keyof Handlers, T extends Handlers[K]>(
   name: K,
   args?: Parameters<T>[0],
 ): Promise<Awaited<ReturnType<T>>> {
-  return injected.send(name, args);
+  return lib.send(name, args);
 }
 
 export async function runImport(

packages/api/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@actual-app/api",
-  "version": "26.3.0",
+  "version": "26.4.0",
   "description": "An API for Actual",
   "license": "MIT",
   "files": [
@@ -9,29 +9,41 @@
   ],
   "main": "dist/index.js",
   "types": "@types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./@types/index.d.ts",
+      "development": "./index.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "types": "./@types/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
   "scripts": {
-    "build:app": "yarn workspace loot-core build:api",
-    "build:crdt": "yarn workspace @actual-app/crdt build",
-    "build:node": "tsc && tsc-alias",
-    "build:migrations": "cp migrations/*.sql dist/migrations",
-    "build:default-db": "cp default-db.sqlite dist/",
-    "build": "yarn run clean && yarn run build:app && yarn run build:node && yarn run build:migrations && yarn run build:default-db",
-    "test": "yarn run clean && yarn run build:app && yarn run build:crdt && vitest --run",
-    "clean": "rm -rf dist @types",
-    "typecheck": "yarn build && tsc --noEmit && tsc-strict"
+    "build": "vite build",
+    "test": "vitest --run",
+    "typecheck": "tsgo -b && tsc-strict"
   },
   "dependencies": {
-    "@actual-app/crdt": "workspace:^",
+    "@actual-app/core": "workspace:*",
+    "@actual-app/crdt": "workspace:*",
     "better-sqlite3": "^12.6.2",
     "compare-versions": "^6.1.1",
-    "node-fetch": "^3.3.2",
     "uuid": "^13.0.0"
   },
   "devDependencies": {
-    "tsc-alias": "^1.8.16",
-    "typescript": "^5.9.3",
+    "@typescript/native-preview": "^7.0.0-dev.20260309.1",
+    "rollup-plugin-visualizer": "^6.0.11",
     "typescript-strict-plugin": "^2.4.4",
-    "vitest": "^4.0.18"
+    "vite": "^8.0.5",
+    "vite-plugin-dts": "^4.5.4",
+    "vite-plugin-peggy-loader": "^2.0.1",
+    "vitest": "^4.1.0"
   },
   "engines": {
     "node": ">=20"

packages/api/tsconfig.json

@@ -5,8 +5,9 @@
     // Using ES2021 because that's the newest version where
     // the latest Node 16.x release supports all of the features
     "target": "ES2021",
-    "module": "CommonJS",
-    "moduleResolution": "node10",
+    "module": "es2022",
+    "moduleResolution": "bundler",
+    "customConditions": ["api"],
     "noEmit": false,
     "declaration": true,
     "declarationMap": true,
@@ -14,13 +15,9 @@
     "rootDir": ".",
     "declarationDir": "@types",
     "tsBuildInfoFile": "dist/.tsbuildinfo",
-    "paths": {
-      // TEMPORARY
-      "loot-core/*": ["../loot-core/src/*"]
-    },
     "plugins": [{ "name": "typescript-strict-plugin", "paths": ["."] }]
   },
   "references": [{ "path": "../crdt" }, { "path": "../loot-core" }],
   "include": ["."],
-  "exclude": ["**/node_modules/*", "dist", "@types", "*.test.ts"]
+  "exclude": ["**/node_modules/*", "dist", "@types", "*.test.ts", "*.config.ts"]
 }

packages/api/typings.ts

@@ -0,0 +1,2 @@
+declare module 'hyperformula/i18n/languages/enUS';
+declare module '*.pegjs';

packages/api/utils.ts

@@ -1,6 +1,4 @@
-// oxlint-disable-next-line typescript/ban-ts-comment
-// @ts-ignore: bundle not available until we build it
-import * as bundle from './app/bundle.api.js';
+import { lib } from '@actual-app/core/server/main';
 
-export const amountToInteger = bundle.lib.amountToInteger;
-export const integerToAmount = bundle.lib.integerToAmount;
+export const amountToInteger = lib.amountToInteger;
+export const integerToAmount = lib.integerToAmount;

packages/api/vite.config.ts

@@ -0,0 +1,97 @@
+import fs from 'fs';
+import path from 'path';
+
+import { visualizer } from 'rollup-plugin-visualizer';
+import { defineConfig } from 'vite';
+import dts from 'vite-plugin-dts';
+import peggyLoader from 'vite-plugin-peggy-loader';
+
+const lootCoreRoot = path.resolve(__dirname, '../loot-core');
+const distDir = path.resolve(__dirname, 'dist');
+const typesDir = path.resolve(__dirname, '@types');
+
+function cleanOutputDirs() {
+  return {
+    name: 'clean-output-dirs',
+    buildStart() {
+      if (fs.existsSync(distDir)) fs.rmSync(distDir, { recursive: true });
+      if (fs.existsSync(typesDir)) fs.rmSync(typesDir, { recursive: true });
+    },
+  };
+}
+
+function copyMigrationsAndDefaultDb() {
+  return {
+    name: 'copy-migrations-and-default-db',
+    closeBundle() {
+      const migrationsSrc = path.join(lootCoreRoot, 'migrations');
+      const defaultDbPath = path.join(lootCoreRoot, 'default-db.sqlite');
+
+      if (!fs.existsSync(migrationsSrc)) {
+        throw new Error(`migrations directory not found at ${migrationsSrc}`);
+      }
+      const migrationsStat = fs.statSync(migrationsSrc);
+      if (!migrationsStat.isDirectory()) {
+        throw new Error(`migrations path is not a directory: ${migrationsSrc}`);
+      }
+
+      const migrationsDest = path.join(distDir, 'migrations');
+      fs.mkdirSync(migrationsDest, { recursive: true });
+      for (const name of fs.readdirSync(migrationsSrc)) {
+        if (name.endsWith('.sql') || name.endsWith('.js')) {
+          fs.copyFileSync(
+            path.join(migrationsSrc, name),
+            path.join(migrationsDest, name),
+          );
+        }
+      }
+
+      if (!fs.existsSync(defaultDbPath)) {
+        throw new Error(`default-db.sqlite not found at ${defaultDbPath}`);
+      }
+      fs.copyFileSync(defaultDbPath, path.join(distDir, 'default-db.sqlite'));
+    },
+  };
+}
+
+export default defineConfig({
+  ssr: {
+    noExternal: true,
+    external: ['better-sqlite3'],
+    resolve: { conditions: ['api'] },
+  },
+  build: {
+    ssr: true,
+    target: 'node20',
+    outDir: distDir,
+    emptyOutDir: true,
+    sourcemap: true,
+    lib: {
+      entry: path.resolve(__dirname, 'index.ts'),
+      formats: ['cjs'],
+      fileName: () => 'index.js',
+    },
+  },
+  plugins: [
+    cleanOutputDirs(),
+    peggyLoader(),
+    dts({
+      tsconfigPath: path.resolve(__dirname, 'tsconfig.json'),
+      outDir: path.resolve(__dirname, '@types'),
+      rollupTypes: true,
+    }),
+    copyMigrationsAndDefaultDb(),
+    visualizer({ template: 'raw-data', filename: 'app/stats.json' }),
+  ],
+  resolve: {
+    conditions: ['api'],
+  },
+  test: {
+    globals: true,
+    onConsoleLog(log: string, type: 'stdout' | 'stderr'): boolean | void {
+      // print only console.error
+      return type === 'stderr';
+    },
+    maxWorkers: 2,
+  },
+});

packages/api/vitest.config.ts

@@ -1,10 +0,0 @@
-export default {
-  test: {
-    globals: true,
-    onConsoleLog(log: string, type: 'stdout' | 'stderr'): boolean | void {
-      // print only console.error
-      return type === 'stderr';
-    },
-    maxWorkers: 2,
-  },
-};

packages/ci-actions/.gitignore

@@ -0,0 +1 @@
+dist/*

packages/ci-actions/bin/check-migrations.ts

@@ -1,14 +1,14 @@
-#!/usr/bin/env node
-
 // overview:
 // 1. Identify the migrations in packages/loot-core/migrations/* on `master` and HEAD
 // 2. Make sure that any new migrations on HEAD are dated after the latest migration on `master`.
 
-const { spawnSync } = require('child_process');
-const path = require('path');
+import { spawnSync } from 'child_process';
+import path from 'path';
+import { fileURLToPath } from 'url';
 
 const migrationsDir = path.join(
-  __dirname,
+  path.dirname(fileURLToPath(import.meta.url)),
+  '..',
   '..',
   '..',
   'packages',
@@ -16,7 +16,7 @@ const migrationsDir = path.join(
   'migrations',
 );
 
-function readMigrations(ref) {
+function readMigrations(ref: string) {
   const { stdout } = spawnSync('git', [
     'ls-tree',
     '--name-only',

packages/ci-actions/bin/get-next-package-version.ts

@@ -2,13 +2,13 @@
 
 // This script is used in GitHub Actions to get the next version based on the current package.json version.
 // It supports three types of versioning: nightly, hotfix, and monthly.
-
 import fs from 'node:fs';
 import { parseArgs } from 'node:util';
 
-import { getNextVersion } from '../src/versions/get-next-package-version.js';
-
-const args = process.argv;
+import {
+  getNextVersion,
+  isValidVersionType,
+} from '../src/versions/get-next-package-version';
 
 const options = {
   'package-json': {
@@ -28,40 +28,53 @@ const options = {
     short: 'u',
     default: false,
   },
-};
+} as const;
+
+function fail(message: string): never {
+  console.error(message);
+  process.exit(1);
+}
 
 const { values } = parseArgs({
-  args,
   options,
   allowPositionals: true,
 });
 
-if (!values['package-json']) {
-  console.error(
+const packageJsonPath = values['package-json'];
+if (!packageJsonPath) {
+  fail(
     'Please specify the path to package.json using --package-json or -p option.',
   );
-  process.exit(1);
 }
 
 try {
-  const packageJsonPath = values['package-json'];
   const packageJson = JSON.parse(fs.readFileSync(packageJsonPath, 'utf8'));
+
+  if (!('version' in packageJson) || typeof packageJson.version !== 'string') {
+    fail('The specified package.json does not contain a valid version field.');
+  }
+
   const currentVersion = packageJson.version;
 
   const explicitVersion = values.version;
   let newVersion;
+
   if (explicitVersion) {
     newVersion = explicitVersion;
   } else {
+    const type = values.type;
+    if (!type || !isValidVersionType(type)) {
+      fail('Please specify the release type using --type or -t.');
+    }
+
     try {
       newVersion = getNextVersion({
         currentVersion,
-        type: values.type,
+        type,
         currentDate: new Date(),
       });
-    } catch (e) {
-      console.error(e.message);
-      process.exit(1);
+    } catch (error) {
+      fail(error instanceof Error ? error.message : String(error));
     }
   }
 
@@ -76,6 +89,5 @@ try {
     );
   }
 } catch (error) {
-  console.error('Error:', error.message);
-  process.exit(1);
+  fail(`Error: ${error instanceof Error ? error.message : String(error)}`);
 }

packages/ci-actions/bin/release-notes-check.mjs

@@ -0,0 +1,68 @@
+import * as fs from 'node:fs';
+
+import matter from 'gray-matter';
+
+import {
+  categoryAutocorrections,
+  categoryOrder,
+} from '../src/release-notes/util.mjs';
+
+console.log('Looking in ' + fs.realpathSync('upcoming-release-notes'));
+
+const expectedPath = `upcoming-release-notes/${process.env.PR_NUMBER}.md`;
+
+function reportError(message) {
+  console.log(`::error::${message}`);
+
+  process.stdout.write('::notice::');
+  fs.createReadStream('upcoming-release-notes/README.md').pipe(process.stdout);
+
+  fs.createReadStream('upcoming-release-notes/README.md')
+    .pipe(fs.createWriteStream(process.env.GITHUB_STEP_SUMMARY))
+    .on('close', () => {
+      process.exit(1);
+    });
+}
+
+(() => {
+  if (!fs.existsSync(expectedPath)) {
+    reportError(`Release note file ${expectedPath} not found`);
+    return;
+  }
+
+  const { data, content } = matter(fs.readFileSync(expectedPath, 'utf-8'));
+
+  if (!data.category) {
+    reportError(`Release note is missing a category.`);
+    return;
+  }
+  if (categoryAutocorrections[data.category]) {
+    data.category = categoryAutocorrections[data.category];
+  }
+  if (!categoryOrder.includes(data.category)) {
+    reportError(
+      `Release note category "${data.category}" is not one of ${categoryOrder
+        .map(JSON.stringify)
+        .join(', ')}`,
+    );
+    return;
+  }
+
+  if (!data.authors) {
+    reportError(`Release note is missing authors.`);
+    return;
+  }
+  if (!Array.isArray(data.authors)) {
+    reportError(`Release note authors should be a list.`);
+    return;
+  }
+
+  if (content.trim().split('\n').length !== 1) {
+    reportError(
+      `Release note file ${expectedPath} body should contain exactly one line`,
+    );
+    return;
+  }
+
+  console.log('Everything looks good! \u{1f389}');
+})();

packages/ci-actions/bin/release-notes-generate.mjs

@@ -0,0 +1,210 @@
+import * as childProcess from 'node:child_process';
+import * as fs from 'node:fs/promises';
+import { join } from 'node:path';
+import { inspect, promisify } from 'node:util';
+
+import matter from 'gray-matter';
+import listify from 'listify';
+
+import {
+  categoryAutocorrections,
+  categoryOrder,
+} from '../src/release-notes/util.mjs';
+
+const exec = promisify(childProcess.exec);
+
+const [owner, repo] = process.env.GITHUB_REPOSITORY.split('/');
+
+const apiResult = await fetch('https://api.github.com/graphql', {
+  method: 'POST',
+  headers: {
+    Authorization: `bearer ${process.env.GITHUB_TOKEN}`,
+    'Content-Type': 'application/json',
+  },
+  body: JSON.stringify({
+    query: /* GraphQL */ `
+      query GetPRMetadata(
+        $name: String!
+        $owner: String!
+        $headRefName: String!
+      ) {
+        repository(name: $name, owner: $owner) {
+          pullRequests(headRefName: $headRefName, first: 1) {
+            edges {
+              node {
+                number
+                headRefName
+              }
+            }
+          }
+        }
+      }
+    `,
+    variables: {
+      name: repo,
+      owner,
+      headRefName: process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME,
+    },
+  }),
+}).then(res => res.json());
+
+await collapsedLog('API Response', apiResult);
+
+const prData = apiResult.data.repository.pullRequests.edges[0].node;
+
+const version = prData.headRefName.split('/')[1].replace(/^v/, '');
+const today = new Date().toISOString().slice(0, 10);
+const author = process.env.GITHUB_ACTOR || 'TODO';
+
+const { notesByCategory, files } = await parseReleaseNotes(
+  'upcoming-release-notes',
+);
+const categorizedNotes = formatNotes(notesByCategory);
+
+await collapsedLog('Release Notes', categorizedNotes);
+
+if (files.length === 0) {
+  console.log('No release notes found, nothing to generate');
+  process.exit(0);
+}
+
+const highlights = '- TODO: Add release highlights';
+
+await group('Generate blog post', async () => {
+  const slug = version.replace(/\./g, '-');
+  const filename = `${today}-release-${slug}.md`;
+  const blogPath = join('packages/docs/blog', filename);
+
+  const blogContent = `---
+title: Release ${version}
+description: New release of Actual.
+date: ${today}T10:00
+slug: release-${version}
+tags: [announcement, release]
+hide_table_of_contents: false
+authors: ${author}
+---
+
+${highlights}
+
+<!--truncate-->
+
+**Docker Tag: v${version}**
+
+${categorizedNotes}
+`;
+
+  await fs.writeFile(blogPath, blogContent);
+  console.log(`Wrote ${blogPath}`);
+});
+
+await group('Update releases.md', async () => {
+  const releasesPath = 'packages/docs/docs/releases.md';
+  const existing = await fs.readFile(releasesPath, 'utf-8');
+
+  const newSection = `## ${version}
+
+Release date: ${today}
+
+${highlights}
+
+**Docker Tag: v${version}**
+
+${categorizedNotes}`;
+
+  const updated = existing.replace(
+    '# Release Notes\n',
+    `# Release Notes\n\n${newSection}\n`,
+  );
+
+  await fs.writeFile(releasesPath, updated);
+  console.log(`Updated ${releasesPath}`);
+});
+
+await group('Remove used release notes', async () => {
+  if (process.env.GITHUB_HEAD_REF) {
+    await exec(`git fetch origin ${process.env.GITHUB_HEAD_REF}`, {
+      stdio: 'inherit',
+    });
+    await exec(`git checkout ${process.env.GITHUB_HEAD_REF}`, {
+      stdio: 'inherit',
+    });
+  }
+  await Promise.all(
+    files.map(f => fs.unlink(join('upcoming-release-notes', f))),
+  );
+});
+
+await group('Commit and push', async () => {
+  await exec(
+    'git add upcoming-release-notes packages/docs/blog packages/docs/docs/releases.md',
+    { stdio: 'inherit' },
+  );
+  const name = 'github-actions[bot]';
+  const email = '41898282+github-actions[bot]@users.noreply.github.com';
+  await exec(`git commit -m 'Generate release notes for v${version}'`, {
+    stdio: 'inherit',
+    env: {
+      ...process.env,
+      GIT_AUTHOR_NAME: name,
+      GIT_COMMITTER_NAME: name,
+      GIT_AUTHOR_EMAIL: email,
+      GIT_COMMITTER_EMAIL: email,
+    },
+  });
+  await exec('git push origin', { stdio: 'inherit' });
+});
+
+async function parseReleaseNotes(dir) {
+  const files = (await fs.readdir(dir)).filter(f => f.match(/^\d+\.md$/));
+  const notes = files.map(async name => {
+    const content = await fs.readFile(join(dir, name), 'utf-8');
+    const { data, content: body } = matter(content);
+    const number = name.replace('.md', '');
+    const authors = listify(
+      data.authors.map(a => `@${a}`),
+      { finalWord: '&' },
+    );
+    return {
+      category: categoryAutocorrections[data.category] ?? data.category,
+      value: `- [#${number}](https://github.com/actualbudget/${repo}/pull/${number}) ${body.trim()} — thanks ${authors}`,
+    };
+  });
+
+  const notesByCategory = (await Promise.all(notes)).reduce(
+    (acc, note) => {
+      if (!acc[note.category]) {
+        console.log(`WARNING: Unrecognized category "${note.category}"`);
+        acc[note.category] = [];
+      }
+      acc[note.category].push(note.value);
+      return acc;
+    },
+    Object.fromEntries(categoryOrder.map(c => [c, []])),
+  );
+
+  return { notesByCategory, files };
+}
+
+function formatNotes(notes) {
+  return Object.entries(notes)
+    .filter(([_, values]) => values.length > 0)
+    .map(([category, values]) => `#### ${category}\n\n${values.join('\n')}`)
+    .join('\n\n');
+}
+
+async function collapsedLog(name, value) {
+  await group(name, () => {
+    if (typeof value === 'string') {
+      console.log(value);
+    } else {
+      console.log(inspect(value, { depth: null }));
+    }
+  });
+}
+
+async function group(name, cb) {
+  console.log(`::group::${name}`);
+  await cb();
+  console.log('::endgroup::');
+}

packages/ci-actions/bin/tsx

@@ -0,0 +1,8 @@
+#!/bin/bash
+set -euo pipefail
+
+cd ../../
+
+script="$1"
+shift
+exec node --import=extensionless/register --experimental-strip-types packages/ci-actions/"$script" "$@"

packages/ci-actions/package.json

@@ -3,9 +3,20 @@
   "private": true,
   "type": "module",
   "scripts": {
-    "test": "vitest --run"
+    "tsx": "bin/tsx",
+    "test": "vitest --run",
+    "typecheck": "tsgo -b"
   },
   "devDependencies": {
-    "vitest": "^4.0.18"
+    "@typescript/native-preview": "^7.0.0-dev.20260309.1",
+    "extensionless": "^2.0.6",
+    "gray-matter": "^4.0.3",
+    "listify": "^1.0.3",
+    "vitest": "^4.1.0"
+  },
+  "extensionless": {
+    "lookFor": [
+      "ts"
+    ]
   }
 }

packages/ci-actions/src/release-notes/util.mjs

@@ -0,0 +1,12 @@
+export const categoryAutocorrections = {
+  Feature: 'Features',
+  Enhancement: 'Enhancements',
+  Bugfix: 'Bugfixes',
+};
+
+export const categoryOrder = [
+  'Features',
+  'Enhancements',
+  'Bugfixes',
+  'Maintenance',
+];

packages/ci-actions/src/versions/get-next-package-version.test.ts

@@ -77,7 +77,7 @@ describe('getNextVersion (lib)', () => {
     expect(() =>
       getNextVersion({
         currentVersion: '25.8.4',
-        type: 'unknown',
+        type: 'unknown' as never,
         currentDate: new Date('2025-08-10'),
       }),
     ).toThrow(/Invalid type/);

packages/ci-actions/src/versions/get-next-package-version.ts

@@ -1,35 +1,69 @@
-function parseVersion(version) {
+export const versionTypeArray = [
+  'auto',
+  'hotfix',
+  'monthly',
+  'nightly',
+] as const;
+export type VersionType = (typeof versionTypeArray)[number];
+
+type ParsedVersion = {
+  versionYear: number;
+  versionMonth: number;
+  versionHotfix: number;
+};
+
+type GetNextVersionOptions = {
+  currentVersion: string;
+  type: VersionType;
+  currentDate?: Date;
+};
+
+function parseVersion(version: string): ParsedVersion {
   const [y, m, p] = version.split('.');
   return {
-    versionYear: parseInt(y, 10),
-    versionMonth: parseInt(m, 10),
-    versionHotfix: parseInt(p, 10),
+    versionYear: Number.parseInt(y, 10),
+    versionMonth: Number.parseInt(m, 10),
+    versionHotfix: Number.parseInt(p, 10),
   };
 }
 
-function computeNextMonth(versionYear, versionMonth) {
-  // Create date and add 1 month
-  const versionDate = new Date(2000 + versionYear, versionMonth - 1, 1); // month is 0-indexed
+function computeNextMonth(versionYear: number, versionMonth: number) {
+  const versionDate = new Date(2000 + versionYear, versionMonth - 1, 1);
   const nextVersionMonthDate = new Date(
     versionDate.getFullYear(),
     versionDate.getMonth() + 1,
     1,
   );
 
-  // Format back to YY.M format
   const fullYear = nextVersionMonthDate.getFullYear();
   const nextVersionYear = fullYear.toString().slice(fullYear < 2100 ? -2 : -3);
-  const nextVersionMonth = nextVersionMonthDate.getMonth() + 1; // Convert back to 1-indexed
+  const nextVersionMonth = nextVersionMonthDate.getMonth() + 1;
+
   return { nextVersionYear, nextVersionMonth };
 }
 
-// Determine logical type from 'auto' based on the current date and version
-function resolveType(type, currentDate, versionYear, versionMonth) {
-  if (type !== 'auto') return type;
+export function isValidVersionType(value: string): value is VersionType {
+  return versionTypeArray.includes(value as VersionType);
+}
+
+function resolveType(
+  type: VersionType,
+  currentDate: Date,
+  versionYear: number,
+  versionMonth: number,
+) {
+  if (type !== 'auto') {
+    return type;
+  }
+
   const inPatchMonth =
     currentDate.getFullYear() === 2000 + versionYear &&
     currentDate.getMonth() + 1 === versionMonth;
-  if (inPatchMonth && currentDate.getDate() <= 25) return 'hotfix';
+
+  if (inPatchMonth && currentDate.getDate() <= 25) {
+    return 'hotfix';
+  }
+
   return 'monthly';
 }
 
@@ -37,7 +71,7 @@ export function getNextVersion({
   currentVersion,
   type,
   currentDate = new Date(),
-}) {
+}: GetNextVersionOptions) {
   const { versionYear, versionMonth, versionHotfix } =
     parseVersion(currentVersion);
   const { nextVersionYear, nextVersionMonth } = computeNextMonth(
@@ -51,11 +85,10 @@ export function getNextVersion({
     versionMonth,
   );
 
-  // Format date stamp once for nightly
   const currentDateString = currentDate
     .toISOString()
     .split('T')[0]
-    .replaceAll('-', '');
+    .replace(/-/g, '');
 
   switch (resolvedType) {
     case 'nightly':
@@ -66,7 +99,7 @@ export function getNextVersion({
       return `${nextVersionYear}.${nextVersionMonth}.0`;
     default:
       throw new Error(
-        'Invalid type specified. Use "auto", "nightly", "hotfix", or "monthly".',
+        `Invalid type ${String(resolvedType satisfies never)} specified. Use "auto", "nightly", "hotfix", or "monthly".`,
       );
   }
 }

packages/ci-actions/tsconfig.json

@@ -0,0 +1,16 @@
+{
+  "compilerOptions": {
+    "target": "ES2022",
+    "lib": [],
+    "module": "es2022",
+    "moduleResolution": "bundler",
+    "skipLibCheck": true,
+    "strict": true,
+    "types": ["node"],
+    "outDir": "dist",
+    "rootDir": ".",
+    "composite": true
+  },
+  "include": ["src/**/*", "bin/**/*"],
+  "exclude": ["node_modules"]
+}

packages/cli/.gitignore

@@ -0,0 +1,7 @@
+dist
+coverage
+.actualrc.json
+.actualrc
+.actualrc.yaml
+.actualrc.yml
+actual.config.js

packages/cli/README.md

@@ -0,0 +1,177 @@
+# @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_SYNC_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_SYNC_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",
+  "syncId": "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                                   |
+| `--sync-id <id>`          | Budget Sync ID                                  |
+| `--data-dir <path>`       | Data directory                                  |
+| `--format <format>`       | Output format: `json` (default), `table`, `csv` |
+| `--verbose`               | Show informational 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; excludes closed by default)
+actual accounts list [--include-closed] --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** when passed as input (flags, JSON):
+
+| CLI Value | Dollar Amount |
+| --------- | ------------- |
+| `5000`    | $50.00        |
+| `-12350`  | -$123.50      |
+
+**Output formatting:** Table (`--format table`) and CSV (`--format csv`) output automatically converts cent values to decimal (e.g. `1665.00` instead of `166500`). JSON output always returns raw cents for programmatic use.
+
+### Tips & Common Pitfalls
+
+- **Split transactions:** When summing or counting transactions, filter `"is_parent": false` to avoid double-counting. A split parent holds the total amount, and its children hold the individual parts — including both would count the total twice.
+
+- **Avoid rapid sequential requests:** Each CLI invocation opens a new server connection. Running queries in a tight loop (e.g. one per month) may trigger rate limiting or authentication failures. Instead, fetch all data in a single query with a date range filter and process locally:
+
+  ```bash
+  # Good: single query for the full year
+  actual query run --table transactions \
+    --filter '{"$and":[{"date":{"$gte":"2025-01-01"}},{"date":{"$lte":"2025-12-31"}}]}' \
+    --limit 5000
+
+  # Bad: one query per month in a loop (may fail with auth errors)
+  for month in 01 02 03 ...; do actual query run ...; done
+  ```
+
+- **Uncategorized transactions:** `category.name` is `null` for transactions without a category. Account for this when filtering or grouping by category.
+
+- **No date sub-fields in AQL:** `date.month`, `date.year`, etc. are not supported as query fields. To group by month, fetch raw transactions with a date range filter and aggregate locally in a script.
+
+## 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_SYNC_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
+```

packages/cli/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@actual-app/cli",
+  "version": "26.4.0",
+  "description": "CLI for Actual Budget",
+  "license": "MIT",
+  "bin": {
+    "actual": "./dist/cli.js",
+    "actual-cli": "./dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "imports": {
+    "#commands/*": "./src/commands/*.ts",
+    "#config": "./src/config.ts",
+    "#connection": "./src/connection.ts",
+    "#input": "./src/input.ts",
+    "#output": "./src/output.ts",
+    "#utils": "./src/utils.ts"
+  },
+  "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.15",
+    "@typescript/native-preview": "^7.0.0-dev.20260309.1",
+    "rollup-plugin-visualizer": "^6.0.11",
+    "vite": "^8.0.5",
+    "vitest": "^4.1.0"
+  },
+  "engines": {
+    "node": ">=22"
+  }
+}

packages/cli/src/commands/accounts.test.ts

@@ -0,0 +1,326 @@
+import * as api from '@actual-app/api';
+import { Command } from 'commander';
+
+import { printOutput } from '#output';
+
+import { registerAccountsCommand } from './accounts';
+
+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(),
+}));
+
+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('--sync-id <id>');
+  program.option('--data-dir <dir>');
+  program.option('--verbose');
+  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 with computed balance', async () => {
+      const accounts = [
+        { id: '1', name: 'Checking', offbudget: false, closed: false },
+      ];
+      vi.mocked(api.getAccounts).mockResolvedValue(accounts);
+
+      await run(['accounts', 'list']);
+
+      expect(api.getAccounts).toHaveBeenCalled();
+      expect(api.getAccountBalance).toHaveBeenCalledWith('1');
+      expect(printOutput).toHaveBeenCalledWith(
+        [
+          {
+            id: '1',
+            name: 'Checking',
+            offbudget: false,
+            closed: false,
+            balance: 10000,
+          },
+        ],
+        undefined,
+      );
+    });
+
+    it('passes format option to printOutput', async () => {
+      vi.mocked(api.getAccounts).mockResolvedValue([]);
+
+      await run(['--format', 'csv', 'accounts', 'list']);
+
+      expect(printOutput).toHaveBeenCalledWith([], 'csv');
+    });
+
+    it('filters out closed accounts by default', async () => {
+      vi.mocked(api.getAccounts).mockResolvedValue([
+        { id: '1', name: 'Open', offbudget: false, closed: false },
+        { id: '2', name: 'Closed', offbudget: false, closed: true },
+      ]);
+
+      await run(['accounts', 'list']);
+
+      expect(printOutput).toHaveBeenCalledWith(
+        [
+          {
+            id: '1',
+            name: 'Open',
+            offbudget: false,
+            closed: false,
+            balance: 10000,
+          },
+        ],
+        undefined,
+      );
+    });
+
+    it('includes closed accounts when --include-closed is passed', async () => {
+      vi.mocked(api.getAccounts).mockResolvedValue([
+        { id: '1', name: 'Open', offbudget: false, closed: false },
+        { id: '2', name: 'Closed', offbudget: false, closed: true },
+      ]);
+
+      await run(['accounts', 'list', '--include-closed']);
+
+      expect(printOutput).toHaveBeenCalledWith(
+        expect.arrayContaining([
+          expect.objectContaining({ id: '2', closed: true }),
+        ]),
+        undefined,
+      );
+    });
+
+    it('sorts on-budget accounts before off-budget', async () => {
+      vi.mocked(api.getAccounts).mockResolvedValue([
+        { id: '1', name: 'OffBudget', offbudget: true, closed: false },
+        { id: '2', name: 'OnBudget', offbudget: false, closed: false },
+      ]);
+
+      await run(['accounts', 'list']);
+
+      const output = vi.mocked(printOutput).mock.calls[0][0] as Array<{
+        id: string;
+      }>;
+      expect(output[0].id).toBe('2'); // on-budget first
+      expect(output[1].id).toBe('1'); // off-budget second
+    });
+  });
+
+  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,
+      );
+    });
+
+    it('passes offbudget true', async () => {
+      await run([
+        'accounts',
+        'update',
+        'acct-1',
+        '--name',
+        'X',
+        '--offbudget',
+        'true',
+      ]);
+
+      expect(api.updateAccount).toHaveBeenCalledWith('acct-1', {
+        name: 'X',
+        offbudget: true,
+      });
+    });
+
+    it('passes offbudget false', async () => {
+      await run([
+        'accounts',
+        'update',
+        'acct-1',
+        '--name',
+        'X',
+        '--offbudget',
+        'false',
+      ]);
+
+      expect(api.updateAccount).toHaveBeenCalledWith('acct-1', {
+        name: 'X',
+        offbudget: false,
+      });
+    });
+
+    it('rejects invalid offbudget value', async () => {
+      await expect(
+        run(['accounts', 'update', 'acct-1', '--offbudget', 'yes']),
+      ).rejects.toThrow(
+        'Invalid --offbudget: "yes". Expected "true" or "false".',
+      );
+    });
+
+    it('rejects empty name', async () => {
+      await expect(
+        run(['accounts', 'update', 'acct-1', '--name', '  ']),
+      ).rejects.toThrow('Invalid --name: must be a non-empty string.');
+    });
+
+    it('rejects update with no fields', async () => {
+      await expect(run(['accounts', 'update', 'acct-1'])).rejects.toThrow(
+        'No update fields provided. Use --name or --offbudget.',
+      );
+    });
+  });
+
+  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'),
+      );
+    });
+  });
+});

packages/cli/src/commands/accounts.ts

@@ -0,0 +1,156 @@
+import * as api from '@actual-app/api';
+import type { Command } from 'commander';
+
+import { withConnection } from '#connection';
+import { printOutput } from '#output';
+import { parseBoolFlag, parseIntFlag } from '#utils';
+
+export function registerAccountsCommand(program: Command) {
+  const accounts = program.command('accounts').description('Manage accounts');
+
+  accounts
+    .command('list')
+    .description('List all accounts')
+    .option('--include-closed', 'Include closed accounts', false)
+    .action(async cmdOpts => {
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        const allAccounts = await api.getAccounts();
+        const accounts = allAccounts.filter(
+          a => cmdOpts.includeClosed || !a.closed,
+        );
+        // Stable sort: on-budget first, off-budget second
+        // (preserves API sort_order within each group)
+        accounts.sort((a, b) => Number(a.offbudget) - Number(b.offbudget));
+        const balances = await Promise.all(
+          accounts.map(a => api.getAccountBalance(a.id)),
+        );
+        const output = accounts.map((a, i) => ({
+          id: a.id,
+          name: a.name,
+          offbudget: a.offbudget,
+          closed: a.closed,
+          balance: balances[i],
+        }));
+        printOutput(output, 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 (e.g. 50000 = 500.00)',
+      '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();
+      const fields: Record<string, unknown> = {};
+      if (cmdOpts.name !== undefined) {
+        const trimmed = cmdOpts.name.trim();
+        if (trimmed === '') {
+          throw new Error('Invalid --name: must be a non-empty string.');
+        }
+        fields.name = trimmed;
+      }
+      if (cmdOpts.offbudget !== undefined) {
+        fields.offbudget = parseBoolFlag(cmdOpts.offbudget, '--offbudget');
+      }
+      if (Object.keys(fields).length === 0) {
+        throw new Error(
+          'No update fields provided. Use --name or --offbudget.',
+        );
+      }
+      await withConnection(opts, async () => {
+        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);
+      });
+    });
+}

packages/cli/src/commands/budgets.ts

@@ -0,0 +1,141 @@
+import * as api from '@actual-app/api';
+import type { Command } from 'commander';
+
+import { resolveConfig } from '#config';
+import { withConnection } from '#connection';
+import { printOutput } from '#output';
+import { parseBoolFlag, 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();
+      const config = await resolveConfig(opts);
+      const password = config.encryptionPassword ?? cmdOpts.encryptionPassword;
+      await withConnection(
+        opts,
+        async () => {
+          await api.downloadBudget(syncId, {
+            password,
+          });
+          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 (e.g. 50000 = 500.00)',
+    )
+    .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 flag = parseBoolFlag(cmdOpts.flag, '--flag');
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        await api.setBudgetCarryover(cmdOpts.month, cmdOpts.category, flag);
+        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 (e.g. 50000 = 500.00)',
+    )
+    .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);
+      });
+    });
+}

packages/cli/src/commands/categories.ts

@@ -0,0 +1,75 @@
+import * as api from '@actual-app/api';
+import type { Command } from 'commander';
+
+import { withConnection } from '#connection';
+import { printOutput } from '#output';
+import { parseBoolFlag } from '#utils';
+
+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 fields: Record<string, unknown> = {};
+      if (cmdOpts.name !== undefined) fields.name = cmdOpts.name;
+      if (cmdOpts.hidden !== undefined) {
+        fields.hidden = parseBoolFlag(cmdOpts.hidden, '--hidden');
+      }
+      if (Object.keys(fields).length === 0) {
+        throw new Error('No update fields provided. Use --name or --hidden.');
+      }
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        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);
+      });
+    });
+}

packages/cli/src/commands/category-groups.ts

@@ -0,0 +1,73 @@
+import * as api from '@actual-app/api';
+import type { Command } from 'commander';
+
+import { withConnection } from '#connection';
+import { printOutput } from '#output';
+import { parseBoolFlag } from '#utils';
+
+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 fields: Record<string, unknown> = {};
+      if (cmdOpts.name !== undefined) fields.name = cmdOpts.name;
+      if (cmdOpts.hidden !== undefined) {
+        fields.hidden = parseBoolFlag(cmdOpts.hidden, '--hidden');
+      }
+      if (Object.keys(fields).length === 0) {
+        throw new Error('No update fields provided. Use --name or --hidden.');
+      }
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        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 transactions to this category ID')
+    .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);
+      });
+    });
+}

packages/cli/src/commands/payees.ts

@@ -0,0 +1,95 @@
+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 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.',
+        );
+      }
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        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 mergeIds = cmdOpts.ids
+        .split(',')
+        .map(id => id.trim())
+        .filter(id => id.length > 0);
+      if (mergeIds.length === 0) {
+        throw new Error(
+          'No valid payee IDs provided in --ids. Provide comma-separated IDs.',
+        );
+      }
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        await api.mergePayees(cmdOpts.target, mergeIds);
+        printOutput({ success: true }, opts.format);
+      });
+    });
+}

packages/cli/src/commands/query.test.ts

@@ -0,0 +1,365 @@
+import * as api from '@actual-app/api';
+import { Command } from 'commander';
+
+import { printOutput } from '#output';
+
+import { parseOrderBy, registerQueryCommand } from './query';
+
+vi.mock('@actual-app/api', () => {
+  const queryObj = {
+    select: vi.fn().mockReturnThis(),
+    filter: vi.fn().mockReturnThis(),
+    orderBy: vi.fn().mockReturnThis(),
+    limit: vi.fn().mockReturnThis(),
+    offset: vi.fn().mockReturnThis(),
+    groupBy: vi.fn().mockReturnThis(),
+    calculate: vi.fn().mockReturnThis(),
+  };
+  return {
+    q: vi.fn().mockReturnValue(queryObj),
+    aqlQuery: vi.fn().mockResolvedValue({ data: [] }),
+  };
+});
+
+vi.mock('#connection', () => ({
+  withConnection: vi.fn((_opts, fn) => fn()),
+}));
+
+vi.mock('#output', () => ({
+  printOutput: vi.fn(),
+}));
+
+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('--sync-id <id>');
+  program.option('--data-dir <dir>');
+  program.option('--verbose');
+  program.exitOverride();
+  registerQueryCommand(program);
+  return program;
+}
+
+async function run(args: string[]) {
+  const program = createProgram();
+  await program.parseAsync(['node', 'test', ...args]);
+}
+
+function getQueryObj() {
+  return vi.mocked(api.q).mock.results[0]?.value;
+}
+
+describe('parseOrderBy', () => {
+  it('parses plain field names', () => {
+    expect(parseOrderBy('date')).toEqual(['date']);
+  });
+
+  it('parses field:desc', () => {
+    expect(parseOrderBy('date:desc')).toEqual([{ date: 'desc' }]);
+  });
+
+  it('parses field:asc', () => {
+    expect(parseOrderBy('amount:asc')).toEqual([{ amount: 'asc' }]);
+  });
+
+  it('parses multiple mixed fields', () => {
+    expect(parseOrderBy('date:desc,amount:asc,id')).toEqual([
+      { date: 'desc' },
+      { amount: 'asc' },
+      'id',
+    ]);
+  });
+
+  it('throws on invalid direction', () => {
+    expect(() => parseOrderBy('date:backwards')).toThrow(
+      'Invalid order direction "backwards"',
+    );
+  });
+
+  it('throws on empty field', () => {
+    expect(() => parseOrderBy('date,,amount')).toThrow('empty field');
+  });
+});
+
+describe('query 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('run', () => {
+    it('builds a basic query from flags', async () => {
+      await run([
+        'query',
+        'run',
+        '--table',
+        'transactions',
+        '--select',
+        'date,amount',
+        '--limit',
+        '5',
+      ]);
+
+      expect(api.q).toHaveBeenCalledWith('transactions');
+      const qObj = getQueryObj();
+      expect(qObj.select).toHaveBeenCalledWith(['date', 'amount']);
+      expect(qObj.limit).toHaveBeenCalledWith(5);
+    });
+
+    it('rejects unknown table name', async () => {
+      await expect(
+        run(['query', 'run', '--table', 'nonexistent']),
+      ).rejects.toThrow('Unknown table "nonexistent"');
+    });
+
+    it('parses order-by with desc direction', async () => {
+      await run([
+        'query',
+        'run',
+        '--table',
+        'transactions',
+        '--order-by',
+        'date:desc,amount:asc',
+      ]);
+
+      const qObj = getQueryObj();
+      expect(qObj.orderBy).toHaveBeenCalledWith([
+        { date: 'desc' },
+        { amount: 'asc' },
+      ]);
+    });
+
+    it('outputs unwrapped data array (not the full result envelope)', async () => {
+      const mockData = [{ id: '1', amount: -500 }];
+      vi.mocked(api.aqlQuery).mockResolvedValueOnce({
+        data: mockData,
+        dependencies: [],
+      });
+
+      await run([
+        'query',
+        'run',
+        '--table',
+        'transactions',
+        '--select',
+        'id,amount',
+      ]);
+
+      expect(printOutput).toHaveBeenCalledWith(mockData, undefined);
+    });
+
+    it('passes --filter as JSON', async () => {
+      await run([
+        'query',
+        'run',
+        '--table',
+        'transactions',
+        '--filter',
+        '{"amount":{"$lt":0}}',
+      ]);
+
+      const qObj = getQueryObj();
+      expect(qObj.filter).toHaveBeenCalledWith({ amount: { $lt: 0 } });
+    });
+  });
+
+  describe('--last flag', () => {
+    it('sets default table, select, orderBy, and limit', async () => {
+      await run(['query', 'run', '--last', '10']);
+
+      expect(api.q).toHaveBeenCalledWith('transactions');
+      const qObj = getQueryObj();
+      expect(qObj.select).toHaveBeenCalledWith([
+        'date',
+        'account.name',
+        'payee.name',
+        'category.name',
+        'amount',
+        'notes',
+      ]);
+      expect(qObj.orderBy).toHaveBeenCalledWith([{ date: 'desc' }]);
+      expect(qObj.limit).toHaveBeenCalledWith(10);
+    });
+
+    it('allows explicit --select override', async () => {
+      await run(['query', 'run', '--last', '5', '--select', 'date,amount']);
+
+      const qObj = getQueryObj();
+      expect(qObj.select).toHaveBeenCalledWith(['date', 'amount']);
+    });
+
+    it('allows explicit --order-by override', async () => {
+      await run(['query', 'run', '--last', '5', '--order-by', 'amount:asc']);
+
+      const qObj = getQueryObj();
+      expect(qObj.orderBy).toHaveBeenCalledWith([{ amount: 'asc' }]);
+    });
+
+    it('allows --table transactions explicitly', async () => {
+      await run(['query', 'run', '--last', '5', '--table', 'transactions']);
+
+      expect(api.q).toHaveBeenCalledWith('transactions');
+    });
+
+    it('errors if --table is not transactions', async () => {
+      await expect(
+        run(['query', 'run', '--last', '5', '--table', 'accounts']),
+      ).rejects.toThrow('--last implies --table transactions');
+    });
+
+    it('errors if --limit is also set', async () => {
+      await expect(
+        run(['query', 'run', '--last', '5', '--limit', '10']),
+      ).rejects.toThrow('--last and --limit are mutually exclusive');
+    });
+  });
+
+  describe('--count flag', () => {
+    it('uses calculate with $count', async () => {
+      vi.mocked(api.aqlQuery).mockResolvedValueOnce({ data: 42 });
+
+      await run(['query', 'run', '--table', 'transactions', '--count']);
+
+      const qObj = getQueryObj();
+      expect(qObj.calculate).toHaveBeenCalledWith({ $count: '*' });
+      expect(printOutput).toHaveBeenCalledWith({ count: 42 }, undefined);
+    });
+
+    it('errors if --select is also set', async () => {
+      await expect(
+        run([
+          'query',
+          'run',
+          '--table',
+          'transactions',
+          '--count',
+          '--select',
+          'date',
+        ]),
+      ).rejects.toThrow('--count and --select are mutually exclusive');
+    });
+  });
+
+  describe('--where alias', () => {
+    it('works the same as --filter', async () => {
+      await run([
+        'query',
+        'run',
+        '--table',
+        'transactions',
+        '--where',
+        '{"amount":{"$gt":0}}',
+      ]);
+
+      const qObj = getQueryObj();
+      expect(qObj.filter).toHaveBeenCalledWith({ amount: { $gt: 0 } });
+    });
+
+    it('errors if both --where and --filter are provided', async () => {
+      await expect(
+        run([
+          'query',
+          'run',
+          '--table',
+          'transactions',
+          '--where',
+          '{}',
+          '--filter',
+          '{}',
+        ]),
+      ).rejects.toThrow('--where and --filter are mutually exclusive');
+    });
+  });
+
+  describe('--offset flag', () => {
+    it('passes offset through to query', async () => {
+      await run([
+        'query',
+        'run',
+        '--table',
+        'transactions',
+        '--offset',
+        '20',
+        '--limit',
+        '10',
+      ]);
+
+      const qObj = getQueryObj();
+      expect(qObj.offset).toHaveBeenCalledWith(20);
+      expect(qObj.limit).toHaveBeenCalledWith(10);
+    });
+  });
+
+  describe('--group-by flag', () => {
+    it('passes group-by through to query', async () => {
+      await run([
+        'query',
+        'run',
+        '--table',
+        'transactions',
+        '--group-by',
+        'category.name',
+        '--select',
+        'category.name,amount',
+      ]);
+
+      const qObj = getQueryObj();
+      expect(qObj.groupBy).toHaveBeenCalledWith(['category.name']);
+    });
+  });
+
+  describe('tables subcommand', () => {
+    it('lists available tables', async () => {
+      await run(['query', 'tables']);
+
+      expect(printOutput).toHaveBeenCalledWith(
+        expect.arrayContaining([
+          { name: 'transactions' },
+          { name: 'accounts' },
+          { name: 'categories' },
+          { name: 'payees' },
+        ]),
+        undefined,
+      );
+    });
+  });
+
+  describe('fields subcommand', () => {
+    it('lists fields for a known table', async () => {
+      await run(['query', 'fields', 'accounts']);
+
+      const output = vi.mocked(printOutput).mock.calls[0][0] as Array<{
+        name: string;
+        type: string;
+      }>;
+      expect(output).toEqual(
+        expect.arrayContaining([
+          expect.objectContaining({ name: 'id', type: 'id' }),
+          expect.objectContaining({ name: 'name', type: 'string' }),
+        ]),
+      );
+    });
+
+    it('errors on unknown table', async () => {
+      await expect(run(['query', 'fields', 'unknown'])).rejects.toThrow(
+        'Unknown table "unknown"',
+      );
+    });
+  });
+});

packages/cli/src/commands/query.ts

@@ -0,0 +1,354 @@
+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 { isRecord, parseIntFlag } from '#utils';
+
+/**
+ * Parse order-by strings like "date:desc,amount:asc,id" into
+ * AQL orderBy format: [{ date: 'desc' }, { amount: 'asc' }, 'id']
+ */
+export function parseOrderBy(
+  input: string,
+): Array<string | Record<string, string>> {
+  return input.split(',').map(part => {
+    const trimmed = part.trim();
+    if (!trimmed) {
+      throw new Error('--order-by contains an empty field');
+    }
+    const colonIndex = trimmed.indexOf(':');
+    if (colonIndex === -1) {
+      return trimmed;
+    }
+    const field = trimmed.slice(0, colonIndex).trim();
+    if (!field) {
+      throw new Error(
+        `Invalid order field in "${trimmed}". Field name cannot be empty.`,
+      );
+    }
+    const direction = trimmed.slice(colonIndex + 1);
+    if (direction !== 'asc' && direction !== 'desc') {
+      throw new Error(
+        `Invalid order direction "${direction}" for field "${field}". Expected "asc" or "desc".`,
+      );
+    }
+    return { [field]: direction };
+  });
+}
+
+// TODO: Import schema from API once it exposes table/field metadata
+const TABLE_SCHEMA: Record<
+  string,
+  Record<string, { type: string; ref?: string }>
+> = {
+  transactions: {
+    id: { type: 'id' },
+    account: { type: 'id', ref: 'accounts' },
+    date: { type: 'date' },
+    amount: { type: 'integer' },
+    payee: { type: 'id', ref: 'payees' },
+    category: { type: 'id', ref: 'categories' },
+    notes: { type: 'string' },
+    imported_id: { type: 'string' },
+    transfer_id: { type: 'id' },
+    cleared: { type: 'boolean' },
+    reconciled: { type: 'boolean' },
+    starting_balance_flag: { type: 'boolean' },
+    imported_payee: { type: 'string' },
+    is_parent: { type: 'boolean' },
+    is_child: { type: 'boolean' },
+    parent_id: { type: 'id' },
+    sort_order: { type: 'float' },
+    schedule: { type: 'id', ref: 'schedules' },
+    'account.name': { type: 'string', ref: 'accounts' },
+    'payee.name': { type: 'string', ref: 'payees' },
+    'category.name': { type: 'string', ref: 'categories' },
+    'category.group.name': { type: 'string', ref: 'category_groups' },
+  },
+  accounts: {
+    id: { type: 'id' },
+    name: { type: 'string' },
+    offbudget: { type: 'boolean' },
+    closed: { type: 'boolean' },
+    sort_order: { type: 'float' },
+  },
+  categories: {
+    id: { type: 'id' },
+    name: { type: 'string' },
+    is_income: { type: 'boolean' },
+    group_id: { type: 'id', ref: 'category_groups' },
+    sort_order: { type: 'float' },
+    hidden: { type: 'boolean' },
+    'group.name': { type: 'string', ref: 'category_groups' },
+  },
+  payees: {
+    id: { type: 'id' },
+    name: { type: 'string' },
+    transfer_acct: { type: 'id', ref: 'accounts' },
+  },
+  rules: {
+    id: { type: 'id' },
+    stage: { type: 'string' },
+    conditions_op: { type: 'string' },
+    conditions: { type: 'json' },
+    actions: { type: 'json' },
+  },
+  schedules: {
+    id: { type: 'id' },
+    name: { type: 'string' },
+    rule: { type: 'id', ref: 'rules' },
+    next_date: { type: 'date' },
+    completed: { type: 'boolean' },
+  },
+};
+
+const AVAILABLE_TABLES = Object.keys(TABLE_SCHEMA).join(', ');
+
+const LAST_DEFAULT_SELECT = [
+  'date',
+  'account.name',
+  'payee.name',
+  'category.name',
+  'amount',
+  'notes',
+];
+
+function buildQueryFromFile(
+  parsed: Record<string, unknown>,
+  fallbackTable: string | undefined,
+) {
+  const table = typeof parsed.table === 'string' ? parsed.table : fallbackTable;
+  if (!table) {
+    throw new Error(
+      '--table is required when the input file lacks a "table" field',
+    );
+  }
+  let queryObj = api.q(table);
+  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);
+  if (typeof parsed.offset === 'number') {
+    queryObj = queryObj.offset(parsed.offset);
+  }
+  if (Array.isArray(parsed.groupBy)) {
+    queryObj = queryObj.groupBy(parsed.groupBy);
+  }
+  return queryObj;
+}
+
+function buildQueryFromFlags(cmdOpts: Record<string, string | undefined>) {
+  const last = cmdOpts.last ? parseIntFlag(cmdOpts.last, '--last') : undefined;
+
+  if (last !== undefined) {
+    if (cmdOpts.table && cmdOpts.table !== 'transactions') {
+      throw new Error(
+        '--last implies --table transactions. Cannot use with --table ' +
+          cmdOpts.table,
+      );
+    }
+    if (cmdOpts.limit) {
+      throw new Error('--last and --limit are mutually exclusive');
+    }
+  }
+
+  const table =
+    cmdOpts.table ?? (last !== undefined ? 'transactions' : undefined);
+  if (!table) {
+    throw new Error('--table is required (or use --file or --last)');
+  }
+
+  if (!(table in TABLE_SCHEMA)) {
+    throw new Error(
+      `Unknown table "${table}". Available tables: ${AVAILABLE_TABLES}`,
+    );
+  }
+
+  if (cmdOpts.where && cmdOpts.filter) {
+    throw new Error('--where and --filter are mutually exclusive');
+  }
+
+  if (cmdOpts.count && cmdOpts.select) {
+    throw new Error('--count and --select are mutually exclusive');
+  }
+
+  let queryObj = api.q(table);
+
+  if (cmdOpts.count) {
+    queryObj = queryObj.calculate({ $count: '*' });
+  } else if (cmdOpts.select) {
+    queryObj = queryObj.select(cmdOpts.select.split(','));
+  } else if (last !== undefined) {
+    queryObj = queryObj.select(LAST_DEFAULT_SELECT);
+  }
+
+  const filterStr = cmdOpts.filter ?? cmdOpts.where;
+  if (filterStr) {
+    queryObj = queryObj.filter(JSON.parse(filterStr));
+  }
+
+  const orderByStr =
+    cmdOpts.orderBy ??
+    (last !== undefined && !cmdOpts.count ? 'date:desc' : undefined);
+  if (orderByStr) {
+    queryObj = queryObj.orderBy(parseOrderBy(orderByStr));
+  }
+
+  const limitVal =
+    last ??
+    (cmdOpts.limit ? parseIntFlag(cmdOpts.limit, '--limit') : undefined);
+  if (limitVal !== undefined) {
+    queryObj = queryObj.limit(limitVal);
+  }
+
+  if (cmdOpts.offset) {
+    queryObj = queryObj.offset(parseIntFlag(cmdOpts.offset, '--offset'));
+  }
+
+  if (cmdOpts.groupBy) {
+    queryObj = queryObj.groupBy(cmdOpts.groupBy.split(','));
+  }
+
+  return queryObj;
+}
+
+const RUN_EXAMPLES = `
+Examples:
+  # Show last 5 transactions (shortcut)
+  actual query run --last 5
+
+  # Transactions ordered by date descending
+  actual query run --table transactions --select "date,amount,payee.name" --order-by "date:desc" --limit 10
+
+  # Filter with JSON (negative amounts = expenses)
+  actual query run --table transactions --filter '{"amount":{"$lt":0}}' --limit 5
+
+  # Count transactions
+  actual query run --table transactions --count
+
+  # Group by category (use --file for aggregate expressions)
+  echo '{"table":"transactions","groupBy":["category.name"],"select":["category.name",{"amount":{"$sum":"$amount"}}]}' | actual query run --file -
+
+  # Pagination
+  actual query run --table transactions --order-by "date:desc" --limit 10 --offset 20
+
+  # Use --where (alias for --filter)
+  actual query run --table transactions --where '{"payee.name":"Grocery Store"}' --limit 5
+
+  # Read query from a JSON file
+  actual query run --file query.json
+
+  # Pipe query from stdin
+  echo '{"table":"transactions","limit":5}' | actual query run --file -
+
+Available tables: ${AVAILABLE_TABLES}
+Use "actual query tables" and "actual query fields <table>" for schema info.
+
+Common filter operators: $eq, $ne, $lt, $lte, $gt, $gte, $like, $and, $or
+See ActualQL docs for full reference: https://actualbudget.org/docs/api/actual-ql/
+
+Tips:
+  - Amounts are stored as integer cents (e.g. 166500 = 1665.00).
+    Table and CSV output auto-formats these as decimals; JSON keeps raw cents.
+  - Filter "is_parent": false to avoid double-counting split transactions.
+  - Fetch all data in a single query with a date range instead of running
+    one query per month — rapid sequential requests may cause auth failures.
+  - date.month, date.year etc. are not supported as fields in AQL.
+    To group by month, fetch raw transactions with a date range filter
+    and aggregate locally (e.g. in a script).`;
+
+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 (use "actual query tables" to list available tables)',
+    )
+    .option('--select <fields>', 'Comma-separated fields to select')
+    .option('--filter <json>', 'Filter as JSON (e.g. \'{"amount":{"$lt":0}}\')')
+    .option(
+      '--where <json>',
+      'Alias for --filter (cannot be used together with --filter)',
+    )
+    .option(
+      '--order-by <fields>',
+      'Fields with optional direction: field1:desc,field2 (default: asc)',
+    )
+    .option('--limit <n>', 'Limit number of results')
+    .option('--offset <n>', 'Skip first N results (for pagination)')
+    .option(
+      '--last <n>',
+      'Show last N transactions (implies --table transactions, --order-by date:desc)',
+    )
+    .option('--count', 'Count matching rows instead of returning them')
+    .option(
+      '--group-by <fields>',
+      'Comma-separated fields to group by (use with aggregate selects)',
+    )
+    .option(
+      '--file <path>',
+      'Read full query object from JSON file (use - for stdin)',
+    )
+    .addHelpText('after', RUN_EXAMPLES)
+    .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);
+
+        if (!isRecord(result) || !('data' in result)) {
+          throw new Error('Query result missing data');
+        }
+
+        if (cmdOpts.count) {
+          printOutput({ count: result.data }, opts.format);
+        } else {
+          printOutput(result.data, opts.format);
+        }
+      });
+    });
+
+  query
+    .command('tables')
+    .description('List available tables for querying')
+    .action(() => {
+      const opts = program.opts();
+      const tables = Object.keys(TABLE_SCHEMA).map(name => ({ name }));
+      printOutput(tables, opts.format);
+    });
+
+  query
+    .command('fields <table>')
+    .description('List fields for a given table')
+    .action((table: string) => {
+      const opts = program.opts();
+      const schema = TABLE_SCHEMA[table];
+      if (!schema) {
+        throw new Error(
+          `Unknown table "${table}". Available tables: ${Object.keys(TABLE_SCHEMA).join(', ')}`,
+        );
+      }
+      const fields = Object.entries(schema).map(([name, info]) => ({
+        name,
+        type: info.type,
+        ...(info.ref ? { ref: info.ref } : {}),
+      }));
+      printOutput(fields, opts.format);
+    });
+}

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);
+      });
+    });
+}

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);
+      });
+    });
+}

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);
+      });
+    });
+}

packages/cli/src/commands/tags.ts

@@ -0,0 +1,74 @@
+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 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;
+      }
+      if (Object.keys(fields).length === 0) {
+        throw new Error(
+          'At least one of --tag, --color, or --description is required',
+        );
+      }
+      const opts = program.opts();
+      await withConnection(opts, async () => {
+        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);
+      });
+    });
+}

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);
+      });
+    });
+}

packages/cli/src/config.test.ts

@@ -0,0 +1,185 @@
+import { homedir } from 'os';
+import { join } from 'path';
+
+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_SYNC_ID',
+    'ACTUAL_DATA_DIR',
+    'ACTUAL_ENCRYPTION_PASSWORD',
+  ];
+
+  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';
+      process.env.ACTUAL_ENCRYPTION_PASSWORD = 'env-enc';
+      mockConfigFile({
+        serverUrl: 'http://file',
+        password: 'filepw',
+        encryptionPassword: 'file-enc',
+      });
+
+      const config = await resolveConfig({
+        serverUrl: 'http://cli',
+        password: 'clipw',
+        encryptionPassword: 'cli-enc',
+      });
+
+      expect(config.serverUrl).toBe('http://cli');
+      expect(config.password).toBe('clipw');
+      expect(config.encryptionPassword).toBe('cli-enc');
+    });
+
+    it('env vars override file config', async () => {
+      process.env.ACTUAL_SERVER_URL = 'http://env';
+      process.env.ACTUAL_PASSWORD = 'envpw';
+      process.env.ACTUAL_ENCRYPTION_PASSWORD = 'env-enc';
+      mockConfigFile({
+        serverUrl: 'http://file',
+        password: 'filepw',
+        encryptionPassword: 'file-enc',
+      });
+
+      const config = await resolveConfig({});
+
+      expect(config.serverUrl).toBe('http://env');
+      expect(config.password).toBe('envpw');
+      expect(config.encryptionPassword).toBe('env-enc');
+    });
+
+    it('file config is used when no CLI opts or env vars', async () => {
+      mockConfigFile({
+        serverUrl: 'http://file',
+        password: 'filepw',
+        syncId: 'budget-1',
+        encryptionPassword: 'file-enc',
+      });
+
+      const config = await resolveConfig({});
+
+      expect(config.serverUrl).toBe('http://file');
+      expect(config.password).toBe('filepw');
+      expect(config.syncId).toBe('budget-1');
+      expect(config.encryptionPassword).toBe('file-enc');
+    });
+  });
+
+  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');
+    });
+  });
+});

packages/cli/src/config.ts

@@ -0,0 +1,139 @@
+import { homedir } from 'os';
+import { join } from 'path';
+
+import { cosmiconfig } from 'cosmiconfig';
+
+import { isRecord } from './utils';
+
+export type CliConfig = {
+  serverUrl: string;
+  password?: string;
+  sessionToken?: string;
+  syncId?: string;
+  dataDir: string;
+  encryptionPassword?: string;
+};
+
+export type CliGlobalOpts = {
+  serverUrl?: string;
+  password?: string;
+  sessionToken?: string;
+  syncId?: string;
+  dataDir?: string;
+  encryptionPassword?: string;
+  format?: 'json' | 'table' | 'csv';
+  verbose?: boolean;
+};
+
+type ConfigFileContent = {
+  serverUrl?: string;
+  password?: string;
+  sessionToken?: string;
+  syncId?: string;
+  dataDir?: string;
+  encryptionPassword?: string;
+};
+
+const configFileKeys: readonly string[] = [
+  'serverUrl',
+  'password',
+  'sessionToken',
+  'syncId',
+  'dataDir',
+  'encryptionPassword',
+];
+
+function validateConfigFileContent(value: unknown): ConfigFileContent {
+  if (!isRecord(value)) {
+    throw new Error(
+      'Invalid config file: expected an object with keys: ' +
+        configFileKeys.join(', '),
+    );
+  }
+  for (const key of Object.keys(value)) {
+    if (!configFileKeys.includes(key)) {
+      throw new Error(`Invalid config file: unknown key "${key}"`);
+    }
+    if (value[key] !== undefined && typeof value[key] !== 'string') {
+      throw new Error(
+        `Invalid config file: key "${key}" must be a string, got ${typeof value[key]}`,
+      );
+    }
+  }
+  return value as ConfigFileContent;
+}
+
+async function loadConfigFile(): Promise<ConfigFileContent> {
+  const explorer = cosmiconfig('actual', {
+    searchPlaces: [
+      'package.json',
+      '.actualrc',
+      '.actualrc.json',
+      '.actualrc.yaml',
+      '.actualrc.yml',
+      'actual.config.json',
+      'actual.config.yaml',
+      'actual.config.yml',
+    ],
+  });
+  const result = await explorer.search();
+  if (result && !result.isEmpty) {
+    return validateConfigFileContent(result.config);
+  }
+  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 syncId =
+    cliOpts.syncId ?? process.env.ACTUAL_SYNC_ID ?? fileConfig.syncId;
+
+  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,
+    syncId,
+    dataDir,
+    encryptionPassword,
+  };
+}

packages/cli/src/connection.test.ts

@@ -0,0 +1,134 @@
+import * as api from '@actual-app/api';
+
+import { resolveConfig } from './config';
+import { withConnection } from './connection';
+
+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(),
+}));
+
+function setConfig(overrides: Record<string, unknown> = {}) {
+  vi.mocked(resolveConfig).mockResolvedValue({
+    serverUrl: 'http://test',
+    password: 'pw',
+    dataDir: '/tmp/data',
+    syncId: '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',
+      verbose: undefined,
+    });
+  });
+
+  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',
+      verbose: undefined,
+    });
+  });
+
+  it('calls api.downloadBudget when syncId is set', async () => {
+    setConfig({ syncId: 'budget-1' });
+
+    await withConnection({}, async () => 'ok');
+
+    expect(api.downloadBudget).toHaveBeenCalledWith('budget-1', {
+      password: undefined,
+    });
+  });
+
+  it('throws when loadBudget is true but syncId is not set', async () => {
+    setConfig({ syncId: undefined });
+
+    await expect(withConnection({}, async () => 'ok')).rejects.toThrow(
+      'Sync ID is required',
+    );
+  });
+
+  it('skips budget download when loadBudget is false and syncId is not set', async () => {
+    setConfig({ syncId: undefined });
+
+    await withConnection({}, async () => 'ok', { loadBudget: false });
+
+    expect(api.downloadBudget).not.toHaveBeenCalled();
+  });
+
+  it('does not call api.downloadBudget when loadBudget is false', async () => {
+    setConfig({ syncId: '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('does not write to stderr by default', async () => {
+    await withConnection({}, async () => 'ok');
+
+    expect(stderrSpy).not.toHaveBeenCalled();
+  });
+
+  it('writes info to stderr when verbose', async () => {
+    await withConnection({ verbose: true }, async () => 'ok');
+
+    expect(stderrSpy).toHaveBeenCalledWith(
+      expect.stringContaining('Connecting to'),
+    );
+  });
+});

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, verbose?: boolean) {
+  if (verbose) {
+    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.verbose);
+
+  if (config.sessionToken) {
+    await api.init({
+      serverURL: config.serverUrl,
+      dataDir: config.dataDir,
+      sessionToken: config.sessionToken,
+      verbose: globalOpts.verbose,
+    });
+  } else if (config.password) {
+    await api.init({
+      serverURL: config.serverUrl,
+      dataDir: config.dataDir,
+      password: config.password,
+      verbose: globalOpts.verbose,
+    });
+  } else {
+    throw new Error(
+      'Authentication required. Provide --password or --session-token, or set ACTUAL_PASSWORD / ACTUAL_SESSION_TOKEN.',
+    );
+  }
+
+  try {
+    if (loadBudget && config.syncId) {
+      info(`Downloading budget ${config.syncId}...`, globalOpts.verbose);
+      await api.downloadBudget(config.syncId, {
+        password: config.encryptionPassword,
+      });
+    } else if (loadBudget && !config.syncId) {
+      throw new Error(
+        'Sync ID is required for this command. Set --sync-id or ACTUAL_SYNC_ID.',
+      );
+    }
+    return await fn();
+  } finally {
+    await api.shutdown();
+  }
+}

packages/cli/src/index.ts

@@ -0,0 +1,70 @@
+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('--sync-id <id>', 'Budget sync ID (env: ACTUAL_SYNC_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('--verbose', 'Show 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) {
+    try {
+      return JSON.stringify(err);
+    } catch {
+      return '<non-serializable error>';
+    }
+  }
+  return String(err);
+}
+
+program.parseAsync(process.argv).catch((err: unknown) => {
+  const message = normalizeThrownMessage(err);
+  process.stderr.write(`Error: ${message}\n`);
+  process.exitCode = 1;
+});

packages/cli/src/input.ts

@@ -0,0 +1,21 @@
+import { readFileSync } from 'fs';
+
+export function readJsonInput(cmdOpts: {
+  data?: string;
+  file?: string;
+}): unknown {
+  if (cmdOpts.data && cmdOpts.file) {
+    throw new Error('Cannot use both --data and --file');
+  }
+  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');
+}

packages/cli/src/output.test.ts

@@ -0,0 +1,194 @@
+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');
+    });
+
+    it('formats amount fields as decimal values', () => {
+      const data = [{ name: 'Groceries', amount: -250000 }];
+      const result = formatOutput(data, 'table');
+      expect(result).toContain('-2500.00');
+      expect(result).not.toContain('-250000');
+    });
+
+    it('formats balance fields as decimal values', () => {
+      const data = [{ id: 'acc1', balance: 166500 }];
+      const result = formatOutput(data, 'table');
+      expect(result).toContain('1665.00');
+    });
+
+    it('formats budgeted and spent fields as decimal values', () => {
+      const data = [{ budgeted: 50000, spent: -32150 }];
+      const result = formatOutput(data, 'table');
+      expect(result).toContain('500.00');
+      expect(result).toContain('-321.50');
+    });
+
+    it('does not format non-amount numeric fields', () => {
+      const data = [{ id: 12345, sort_order: 100 }];
+      const result = formatOutput(data, 'table');
+      expect(result).toContain('12345');
+      expect(result).toContain('100');
+    });
+  });
+
+  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');
+    });
+
+    it('formats amount fields as decimal values', () => {
+      const data = [{ name: 'Coffee', amount: -2500 }];
+      const result = formatOutput(data, 'csv');
+      const lines = result.split('\n');
+      expect(lines[0]).toBe('name,amount');
+      expect(lines[1]).toBe('Coffee,-25.00');
+    });
+
+    it('does not format amount fields in json output', () => {
+      const data = [{ amount: 166500 }];
+      const result = formatOutput(data, 'json');
+      expect(result).toContain('166500');
+      expect(result).not.toContain('1665.00');
+    });
+  });
+});
+
+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');
+  });
+});

packages/cli/src/output.ts

@@ -0,0 +1,107 @@
+import Table from 'cli-table3';
+
+export type OutputFormat = 'json' | 'table' | 'csv';
+
+// Fields containing integer-cent values, auto-formatted as decimals in table/csv output.
+const AMOUNT_FIELDS = new Set([
+  'amount',
+  'balance',
+  'balance_available',
+  'balance_current',
+  'balance_limit',
+  'budgeted',
+  'spent',
+  'carryover',
+]);
+
+function isAmountValue(key: string, value: unknown): value is number {
+  return AMOUNT_FIELDS.has(key) && typeof value === 'number';
+}
+
+function formatCellValue(key: string, value: unknown): string {
+  if (isAmountValue(key, value)) {
+    return (value / 100).toFixed(2);
+  }
+  return String(value ?? '');
+}
+
+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]: formatCellValue(key, 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 => formatCellValue(k, 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(([k, v]) => escapeCsv(formatCellValue(k, 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(formatCellValue(k, 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');
+}

packages/cli/src/utils.test.ts

@@ -0,0 +1,65 @@
+import { parseBoolFlag, parseIntFlag } from './utils';
+
+describe('parseBoolFlag', () => {
+  it('parses "true"', () => {
+    expect(parseBoolFlag('true', '--flag')).toBe(true);
+  });
+
+  it('parses "false"', () => {
+    expect(parseBoolFlag('false', '--flag')).toBe(false);
+  });
+
+  it('rejects other strings', () => {
+    expect(() => parseBoolFlag('yes', '--flag')).toThrow(
+      'Invalid --flag: "yes". Expected "true" or "false".',
+    );
+  });
+
+  it('includes the flag name in the error message', () => {
+    expect(() => parseBoolFlag('1', '--offbudget')).toThrow(
+      'Invalid --offbudget',
+    );
+  });
+});
+
+describe('parseIntFlag', () => {
+  it('parses a valid integer string', () => {
+    expect(parseIntFlag('42', '--balance')).toBe(42);
+  });
+
+  it('parses zero', () => {
+    expect(parseIntFlag('0', '--balance')).toBe(0);
+  });
+
+  it('parses negative integers', () => {
+    expect(parseIntFlag('-10', '--balance')).toBe(-10);
+  });
+
+  it('rejects decimal values', () => {
+    expect(() => parseIntFlag('3.5', '--balance')).toThrow(
+      'Invalid --balance: "3.5". Expected an integer.',
+    );
+  });
+
+  it('rejects non-numeric strings', () => {
+    expect(() => parseIntFlag('abc', '--balance')).toThrow(
+      'Invalid --balance: "abc". Expected an integer.',
+    );
+  });
+
+  it('rejects partially numeric strings', () => {
+    expect(() => parseIntFlag('3abc', '--balance')).toThrow(
+      'Invalid --balance: "3abc". Expected an integer.',
+    );
+  });
+
+  it('rejects empty string', () => {
+    expect(() => parseIntFlag('', '--balance')).toThrow(
+      'Invalid --balance: "". Expected an integer.',
+    );
+  });
+
+  it('includes the flag name in the error message', () => {
+    expect(() => parseIntFlag('x', '--amount')).toThrow('Invalid --amount');
+  });
+});

packages/cli/src/utils.ts

@@ -0,0 +1,20 @@
+export function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+export function parseBoolFlag(value: string, flagName: string): boolean {
+  if (value !== 'true' && value !== 'false') {
+    throw new Error(
+      `Invalid ${flagName}: "${value}". Expected "true" or "false".`,
+    );
+  }
+  return value === 'true';
+}
+
+export function parseIntFlag(value: string, flagName: string): number {
+  const parsed = value.trim() === '' ? NaN : Number(value);
+  if (!Number.isInteger(parsed)) {
+    throw new Error(`Invalid ${flagName}: "${value}". Expected an integer.`);
+  }
+  return parsed;
+}

packages/cli/tsconfig.json

@@ -0,0 +1,15 @@
+{
+  "extends": "../../tsconfig.json",
+  "compilerOptions": {
+    "composite": true,
+    "lib": ["ES2021"],
+    "types": ["vitest/globals", "node"],
+    "noEmit": false,
+    "strict": true,
+    "outDir": "dist",
+    "tsBuildInfoFile": "dist/.tsbuildinfo"
+  },
+  "references": [{ "path": "../api" }],
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "coverage"]
+}