Actual Budget (actualbudget/docs)

Actual Budget

https://github.com/actualbudget/docs
Admin
Actual Budget is a personal finance software that helps users manage their money locally on their...

Tokens:106,379
Snippets:1,124
Trust Score:8.5
Update:3 months ago
Show doc for...
Context Summary (auto-generated)
Raw
# Actual Budget Documentation

## Introduction

Actual Budget is a super fast and privacy-focused personal finance application that implements the well-proven Envelope Budgeting methodology. This repository contains the community documentation website for Actual Budget, built using Docusaurus 3, a modern static website generator. The documentation provides comprehensive guides, API references, and tutorials to help users install, configure, and use Actual Budget effectively across multiple platforms including self-hosted servers, Docker, Fly.io, and PikaPods.

The documentation site serves as the central hub for all Actual Budget information, featuring installation instructions, user guides for budgeting and transaction management, API documentation for developers, migration guides from other budgeting tools (like YNAB), and release notes. Built with React and Docusaurus, it supports features like blog posts, search functionality via @easyops-cn/docusaurus-search-local, Mermaid diagrams, pan-zoom capabilities for diagrams, and both light and dark themes. The site is designed to be a living document that continuously evolves with the project.

## API - Programmatic Data Access

Initialize and connect to an Actual Budget server to access budget data programmatically.

```javascript
const api = require('@actual-app/api');

(async () => {
  // Initialize connection to server
  await api.init({
    // Local cache directory for budget data
    dataDir: '/home/user/.actual-data',
    // URL of your Actual Budget server
    serverURL: 'http://localhost:5006',
    // Server password
    password: 'your-password'
  });

  // Download budget file (Sync ID from Settings → Show advanced settings → Sync ID)
  await api.downloadBudget('1cfdbb80-6274-49bf-b0c2-737235a4c81f');

  // Get budget data for specific month
  const budget = await api.getBudgetMonth('2024-01');
  console.log(budget);

  // Always shutdown when done
  await api.shutdown();
})();
```

## API - Import Transactions

Import transactions from external sources with automatic reconciliation and deduplication.

```javascript
const api = require('@actual-app/api');

(async () => {
  await api.init({
    dataDir: '/home/user/.actual-data',
    serverURL: 'http://localhost:5006',
    password: 'your-password'
  });

  await api.downloadBudget('1cfdbb80-6274-49bf-b0c2-737235a4c81f');

  // Get account ID
  const accounts = await api.getAccounts();
  const checkingAccount = accounts.find(acct => acct.name === 'Checking');

  // Import transactions (amounts in cents, no decimals)
  const result = await api.importTransactions(checkingAccount.id, [
    {
      date: '2024-01-15',
      amount: -4599,  // -$45.99
      payee_name: 'Kroger',
      notes: 'Weekly groceries',
      imported_id: 'bank_tx_123456'  // Unique ID prevents duplicates
    },
    {
      date: '2024-01-16',
      amount: -2500,  // -$25.00
      payee_name: 'Gas Station',
      category_id: 'c179c3f4-28a6-4fbd-a54d-195cced07a80'
    }
  ]);

  console.log(`Added: ${result.added.length}, Updated: ${result.updated.length}`);

  await api.shutdown();
})();
```

## API - Query Transactions with ActualQL

Query and filter transaction data using ActualQL query language.

```javascript
const api = require('@actual-app/api');

(async () => {
  await api.init({
    dataDir: '/home/user/.actual-data',
    serverURL: 'http://localhost:5006',
    password: 'your-password'
  });

  await api.downloadBudget('1cfdbb80-6274-49bf-b0c2-737235a4c81f');

  // Query transactions for specific category and date range
  const { data: transactions } = await api.runQuery(
    api.q('transactions')
      .filter({
        'category.name': 'Food',
        date: [
          { $gte: '2024-01-01' },
          { $lte: '2024-01-31' }
        ]
      })
      .select(['id', 'date', 'amount', 'payee.name'])
      .orderBy({ date: 'desc' })
  );

  console.log(`Found ${transactions.length} transactions`);
  transactions.forEach(tx => {
    console.log(`${tx.date}: ${tx['payee.name']} - $${tx.amount / 100}`);
  });

  await api.shutdown();
})();
```

## API - Aggregate Transaction Data

Calculate totals and aggregates grouped by payee or category.

```javascript
const api = require('@actual-app/api');

(async () => {
  await api.init({
    dataDir: '/home/user/.actual-data',
    serverURL: 'http://localhost:5006',
    password: 'your-password'
  });

  await api.downloadBudget('1cfdbb80-6274-49bf-b0c2-737235a4c81f');

  // Get total spending by category for year
  const { data: categoryTotals } = await api.runQuery(
    api.q('transactions')
      .filter({
        date: { $transform: '$year', $eq: '2024' }
      })
      .groupBy('category.name')
      .orderBy(['category.group.sort_order', 'category.sort_order'])
      .select([
        'category.group.name',
        'category.name',
        { amount: { $sum: '$amount' } }
      ])
  );

  categoryTotals.forEach(row => {
    console.log(
      `${row['category.group.name']}/${row['category.name']}: $${row.amount / 100}`
    );
  });

  await api.shutdown();
})();
```

## API - Manage Accounts

Create and manage budget accounts programmatically.

```javascript
const api = require('@actual-app/api');

(async () => {
  await api.init({
    dataDir: '/home/user/.actual-data',
    serverURL: 'http://localhost:5006',
    password: 'your-password'
  });

  await api.downloadBudget('1cfdbb80-6274-49bf-b0c2-737235a4c81f');

  // Create new savings account with initial balance
  const accountId = await api.createAccount({
    name: 'Ally Savings',
    type: 'savings',
    offbudget: false
  }, 500000);  // $5,000.00 initial balance

  console.log(`Created account with ID: ${accountId}`);

  // Get all accounts
  const accounts = await api.getAccounts();
  console.log(`Total accounts: ${accounts.length}`);

  // Update account name
  await api.updateAccount(accountId, { name: 'Ally High-Yield Savings' });

  // Get account balance
  const balance = await api.getAccountBalance(accountId);
  console.log(`Current balance: $${balance / 100}`);

  await api.shutdown();
})();
```

## API - Create Rules for Auto-Categorization

Create transaction rules to automatically categorize incoming transactions.

```javascript
const api = require('@actual-app/api');

(async () => {
  await api.init({
    dataDir: '/home/user/.actual-data',
    serverURL: 'http://localhost:5006',
    password: 'your-password'
  });

  await api.downloadBudget('1cfdbb80-6274-49bf-b0c2-737235a4c81f');

  // Get category ID
  const categories = await api.getCategories();
  const foodCategory = categories.find(cat => cat.name === 'Food');

  // Create rule: if payee contains "Kroger", set category to Food
  const rule = await api.createRule({
    stage: 'pre',
    conditionsOp: 'and',
    conditions: [
      {
        field: 'payee',
        op: 'contains',
        value: 'Kroger'
      }
    ],
    actions: [
      {
        op: 'set',
        field: 'category',
        value: foodCategory.id
      }
    ]
  });

  console.log(`Created rule with ID: ${rule.id}`);

  await api.shutdown();
})();
```

## API - Custom Data Importer

Build custom importer to migrate data from another budgeting application.

```javascript
const api = require('@actual-app/api');
const fs = require('fs');

// Load data from external source
const externalData = JSON.parse(fs.readFileSync('my-budget-export.json', 'utf8'));

(async () => {
  await api.init({
    dataDir: '/home/user/.actual-data',
    serverURL: 'http://localhost:5006',
    password: 'your-password'
  });

  // runImport creates new budget file and runs faster bulk import
  await api.runImport('Imported-Budget-2024', async () => {
    // Create all accounts
    for (const account of externalData.accounts) {
      const accountId = await api.createAccount({
        name: account.name,
        type: account.type,
        offbudget: account.offBudget
      }, account.balance);

      // Add transactions using addTransactions (not importTransactions)
      // addTransactions skips reconciliation for raw data import
      const transactions = externalData.transactions
        .filter(tx => tx.accountId === account.id)
        .map(tx => ({
          date: tx.date,
          amount: Math.round(tx.amount * 100),  // Convert to cents
          payee_name: tx.payee,
          notes: tx.memo,
          cleared: tx.cleared
        }));

      await api.addTransactions(accountId, transactions);
    }
  });

  console.log('Import completed successfully');
  await api.shutdown();
})();
```

## Docusaurus - Local Development

Start local development server to preview documentation changes.

```bash
# Install dependencies
yarn

# Start development server (opens browser at http://localhost:3000)
yarn start

# Build static site for production
yarn build

# Serve production build locally
yarn serve

# Format all files with Prettier
yarn format

# Check formatting without making changes
yarn lint
```

## Docusaurus - Configuration

Configure Docusaurus site settings, theme, and plugins.

```javascript
// docusaurus.config.js
module.exports = {
  title: 'Actual Budget Documentation',
  tagline: 'Your finances - made simple',
  url: 'https://actualbudget.org/',
  baseUrl: '/',
  onBrokenLinks: 'throw',
  favicon: 'img/favicon.ico',

  i18n: {
    defaultLocale: 'en',
    locales: ['en'],
  },

  markdown: {
    mermaid: true,
    hooks: {
      onBrokenMarkdownLinks: 'warn',
    },
  },

  themes: ['@docusaurus/theme-mermaid'],

  presets: [
    [
      'classic',
      {
        docs: {
          routeBasePath: 'docs',
          sidebarPath: require.resolve('./docs-sidebar.js'),
          editUrl: 'https://github.com/actualbudget/docs/tree/master/',
        },
        blog: {
          feedOptions: {
            type: 'rss',
            title: 'Actual Budget Blog',
          },
        },
        theme: {
          customCss: require.resolve('./src/css/custom.css'),
        },
      },
    ],
  ],

  plugins: [
    [
      require.resolve('@easyops-cn/docusaurus-search-local'),
      {
        hashed: true,
        indexDocs: true,
        indexPages: false,
        language: 'en',
      },
    ],
    ['@docusaurus/plugin-ideal-image', { disableInDev: false }],
    '@r74tech/docusaurus-plugin-panzoom',
  ],
};
```

## Summary

The Actual Budget Documentation repository serves as a comprehensive resource for users and developers working with Actual Budget. The primary use cases include: learning how to install and configure Actual Budget on various platforms, understanding budgeting concepts and transaction management workflows, building custom integrations using the JavaScript API, migrating data from other budgeting applications like YNAB, and contributing to the documentation itself. The API is particularly powerful for developers who want to automate transaction imports from banks or other financial sources, create custom reporting tools, or build specialized workflows on top of Actual Budget.

The documentation site's integration patterns demonstrate modern web development practices using React and Docusaurus. Contributors can add new documentation pages as Markdown files in the `docs/` directory, create blog posts about releases or features, customize the site appearance through React components and CSS modules, and extend functionality through Docusaurus plugins. The API follows a straightforward pattern: initialize connection, load budget file, perform operations (query data, create/update records), and shutdown. All monetary amounts are handled as integers (cents) to avoid floating-point arithmetic issues, and the ActualQL query language provides a MongoDB-like interface for complex data queries with support for filtering, grouping, aggregation, and transformation operations.