### Workspace command examples

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/contributing/development-setup.md

Common examples for running tests, starting servers, and building packages.

```bash
# Run tests for @actual-app/core
yarn workspace @actual-app/core run test

# Start the docs development server
yarn workspace docs start

# Build the API package
yarn workspace @actual-app/api build
```

--------------------------------

### Balances Properties Log Example for Starting Balance Calculation

Source: https://github.com/actualbudget/actual/blob/master/packages/sync-server/src/app-gocardless/README.md

Example log output for available balances and transactions, used to implement the `calculateStartingBalance` function. It includes balance types and transaction details.

```log
Available (first 10) transactions properties for new integration of institution in calculateStartingBalance function {
  balances: '[
    {
      "balanceAmount": {
        "amount": "448.52",
        "currency": "EUR"
      },
      "balanceType": "forwardAvailable"
    },
    {
      "balanceAmount": {
        "amount": "448.52",
        "currency": "EUR"
      },
      "balanceType": "interimBooked"
    }
  ]',
    top10SortedTransactions: '[
    {
      "transactionId": "20220101001",
      "bookingDate": "2022-01-01",
      "valueDate": "2022-01-01",
      "transactionAmount": {
        "amount": "5.01",
        "currency": "EUR"
      },
      "creditorName": "JOHN EXAMPLE",
      "creditorAccount": {
        "iban": "PL00000000000000000987654321"
      },
      "debtorName": "CHRIS EXAMPLE",
      "debtorAccount": {
        "iban": "PL12345000000000000987654321"
      },
      "remittanceInformationUnstructured": "TEST BANK TRANSFER",
      "remittanceInformationUnstructuredArray": [
        "TEST BANK TRANSFER"
      ]
    }
  ]'
```

--------------------------------

### Install Project Dependencies

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/README.md

Run this command in the project directory to install all necessary dependencies for the documentation site.

```bash
$ yarn
```

--------------------------------

### Clone and Install Actual Dependencies

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/install/build-from-source.md

Commands to clone the repository, navigate to the directory, and install required dependencies.

```bash
git clone https://github.com/actualbudget/actual.git
```

```bash
cd actual
```

```bash
yarn install
```

--------------------------------

### Start Local Development Server

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/README.md

Starts a local development server for the documentation site. Changes are reflected live without server restarts.

```bash
$ yarn start
```

--------------------------------

### Start the server

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/actual-server-repo-move.md

Command to launch the server after migration.

```bash
yarn start:server
```

--------------------------------

### Build and Start the Actual Server

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/install/build-from-source.md

Commands to compile the server and initiate the startup process.

```bash
yarn build:server
```

```bash
yarn start:server
```

--------------------------------

### Install server dependencies

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/actual-server-repo-move.md

Command to install necessary dependencies for the server.

```bash
yarn install
```

--------------------------------

### Install Actual Server CLI

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/install/cli-tool.md

Installs the Actual sync-server globally using npm. Node.js v22 or higher is required.

```bash
npm install --location=global @actual-app/sync-server
```

--------------------------------

### Install Fly.io CLI on Windows

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/install/fly.md

Use PowerShell to download and execute the Fly.io installation script.

```powershell
iwr https://fly.io/install.ps1 -useb | iex
```

--------------------------------

### Start Docker Compose

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/contributing/development-setup.md

Starts the development container from the repository root.

```bash
docker compose up --build
```

--------------------------------

### Start the development server

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/contributing/development-setup.md

Launch the development server, typically accessible at http://localhost:3001/.

```bash
yarn start
```

--------------------------------

### Start sync-server

Source: https://github.com/actualbudget/actual/blob/master/AGENTS.md

Command to initiate the synchronization server.

```bash
yarn workspace @actual-app/sync-server start
```

--------------------------------

### Verify Git Installation

Source: https://github.com/actualbudget/actual/wiki/Fly.io-git

After installing Git, execute this command in the command prompt to confirm the installation and check the installed version.

```cmd
git --version
```

--------------------------------

### Install Actual Budget API

Source: https://github.com/actualbudget/actual/blob/master/packages/api/README.md

Install the Actual Budget API package using npm. This is the first step to using the API in your project.

```bash
npm install @actual-app/api
```

--------------------------------

### Quick Start Usage

Source: https://github.com/actualbudget/actual/blob/master/packages/cli/README.md

Set required environment variables and execute basic commands to interact with budget data.

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

--------------------------------

### Install CLI package

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/api/cli.md

Commands to install the CLI package locally or globally.

```bash
npm install --save @actual-app/cli
```

```bash
npm install --location=global @actual-app/cli
```

--------------------------------

### Start Browser Build with Yarn

Source: https://github.com/actualbudget/actual/wiki/Building-Windows

Execute this command in Git Bash to start the build process for the browser version of Actual Budget. Open your browser to localhost:3001 to view the application.

```bash
yarn start:browser
```

--------------------------------

### Start Development Servers

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/contributing/development-setup.md

Launches various development servers for the browser, sync functionality, or desktop application.

```bash
# Start browser development server
yarn start
# or explicitly:
yarn start:browser

# Start with sync server (for testing sync functionality)
yarn start:server-dev

# Start desktop app development
yarn start:desktop
```

--------------------------------

### Install the CLI

Source: https://github.com/actualbudget/actual/blob/master/packages/cli/README.md

Install the package globally using npm. Requires Node.js version 22 or higher.

```bash
npm install -g @actual-app/cli
```

--------------------------------

### Manage desktop-client development and testing

Source: https://github.com/actualbudget/actual/blob/master/AGENTS.md

Commands for starting the development server, building the project, and running various test suites for the web client.

```bash
# Development
yarn workspace @actual-app/web start:browser

# Build
yarn workspace @actual-app/web build

# E2E tests
yarn workspace @actual-app/web e2e

# Visual regression tests
yarn workspace @actual-app/web vrt
```

--------------------------------

### Start Dev Instance for Visual Regression

Source: https://github.com/actualbudget/actual/blob/master/packages/desktop-client/README.md

Starts a local development instance with HTTPS enabled, required before running visual regression tests against the local server.

```sh
HTTPS=true yarn start
```

```sh
HTTPS=true docker compose up --build
```

--------------------------------

### Install flyctl using PowerShell

Source: https://github.com/actualbudget/actual/wiki/Fly.io-git

Run this command in PowerShell to install the flyctl tool. Ensure you have administrative privileges if prompted.

```powershell
iwr https://fly.io/install.ps1 -useb | iex
```

--------------------------------

### Start Electron Build with Yarn

Source: https://github.com/actualbudget/actual/wiki/Building-Windows

Run this command in Git Bash to start the build process for the Electron version of Actual Budget. If an error occurs, try rerunning the command or executing 'yarn rebuild-electron'.

```bash
yarn start
```

--------------------------------

### Install the Actual API package

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/api/index.md

Use npm or yarn to add the official Actual API client to your project.

```bash
npm install --save @actual-app/api
```

```bash
yarn add @actual-app/api
```

--------------------------------

### Run CLI commands

Source: https://github.com/actualbudget/actual/blob/master/packages/cli/README.md

General usage examples for managing accounts, transactions, budgets, and running queries via the CLI.

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

--------------------------------

### Run type checking

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/contributing/development-setup.md

Verify the project setup by running the type checker.

```bash
yarn typecheck
```

--------------------------------

### Run CLI in Development

Source: https://github.com/actualbudget/actual/blob/master/packages/cli/README.md

Steps to build, start the server, and execute CLI commands locally 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
```

--------------------------------

### Prepare Husky Hooks

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/contributing/troubleshooting.md

Set up Git hooks managed by Husky. Run this command to ensure pre-commit hooks are correctly installed.

```bash
yarn prepare
```

--------------------------------

### Launch Docker container

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/install/docker.md

Starts the Actual server container manually with persistent storage and port mapping.

```bash
$ docker run --pull=always --restart=unless-stopped -d -p 5006:5006 -v YOUR/PATH/TO/DATA:/data --name my_actual_budget actualbudget/actual-server:latest
```

--------------------------------

### Launch Actual on Fly.io

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/install/fly.md

Initializes the application deployment using the specified Docker image.

```bash
fly launch --image actualbudget/actual-server:latest
```

--------------------------------

### Install Yarn globally

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/install/build-from-source.md

Use this command to install the Yarn package manager globally on your system.

```bash
npm install --global yarn
```

--------------------------------

### Connect to an Actual server

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/api/index.md

Initialize the API client and download a budget file using server credentials.

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

(async () => {
  await api.init({
    // Budget data will be cached locally here, in subdirectories for each file.
    dataDir: '/some/path',
    // This is the URL of your running server
    serverURL: 'http://localhost:5006',
    // This is the password you use to log into the server
    password: 'hunter2',
  });

  // This is the ID from Settings → Show advanced settings → Sync ID
  await api.downloadBudget('1cfdbb80-6274-49bf-b0c2-737235a4c81f');
  // or, if you have end-to-end encryption enabled:
  await api.downloadBudget('1cfdbb80-6274-49bf-b0c2-737235a4c81f', {
    password: 'password1',
  });

  let budget = await api.getBudgetMonth('2019-10');
  console.log(budget);
  await api.shutdown();
})();
```

--------------------------------

### Install Dependencies with Yarn

Source: https://github.com/actualbudget/actual/wiki/Building-Windows

Run this command in Git Bash after cloning the repository to install project dependencies.

```bash
yarn install
```

--------------------------------

### Install Fly.io CLI on macOS

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/install/fly.md

Use the terminal to download and execute the Fly.io installation script via shell.

```bash
curl -L https://fly.io/install.sh | sh
```

--------------------------------

### Example Configuration File

Source: https://github.com/actualbudget/actual/blob/master/packages/cli/README.md

Define connection and cache settings in a JSON configuration file. Ensure file permissions are restrictive if storing sensitive information.

```json
{
  "serverUrl": "http://localhost:5006",
  "password": "your-password",
  "syncId": "1cfdbb80-6274-49bf-b0c2-737235a4c81f",
  "cacheTtl": 60,
  "lockTimeout": 10,
  "noLock": false
}
```

--------------------------------

### Install Playwright Browsers

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/contributing/troubleshooting.md

Ensure Playwright browsers are installed for running end-to-end tests. This command is specific to the web workspace.

```bash
yarn workspace @actual-app/web run playwright install
```

--------------------------------

### Run Actual Server with Environment Variable Configuration

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/install/cli-tool.md

Starts the Actual server using a specified config file and an environment variable for the data directory.

```bash
ACTUAL_DATA_DIR=./custom-directory actual-server --config ./config.json
```

--------------------------------

### Extract timeframe start with QUERY_EXTRACT_TIMEFRAME_START

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/experimental/formulas.md

Extracts the start month from a named query's date range for use in BUDGET_QUERY.

```text
=QUERY_EXTRACT_TIMEFRAME_START("expenses")
```

--------------------------------

### api.init(options)

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/api/index.md

Initializes the Actual Budget API in the browser, setting up the Web Worker and connecting to the specified server.

```APIDOC
## api.init(options)

### Description
Initializes the API environment. In the browser, this starts a Web Worker and prepares the virtual file system in IndexedDB.

### Parameters
- **dataDir** (string) - Required - The path inside the virtual file system where budget data is stored.
- **serverURL** (string) - Required - The URL of the Actual Budget server.
- **password** (string) - Required - The password for authentication.
```

--------------------------------

### Run Actual Server with Custom Configuration

Source: https://github.com/actualbudget/actual/blob/master/packages/sync-server/README.md

Executes the Actual server with a specified configuration file.

```bash
actual-server --config ./config.json
```

--------------------------------

### Decline Postgres database setup during fly launch

Source: https://github.com/actualbudget/actual/wiki/Fly.io-image

Select 'No' when prompted to create a Postgres database during 'fly launch' if you do not require it for your setup.

```sh
? Would you like to setup a Postgresql database now? (y/N) n
```

--------------------------------

### init

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/api/index.md

Initializes the connection to the Actual Budget server and loads the budget data.

```APIDOC
## init

### Description
Call this before attempting to use any of the API methods. This will connect to the server using the provided password and load the budget data.

### Signature
`init({ dataDir: string, serverURL: string, password: string, verbose: boolean }): Promise<void>`

### Parameters
- **dataDir** (string) - Optional - Defaults to the current working directory.
- **serverURL** (string) - Optional - If not provided, no network connections will be made.
- **password** (string) - Required - Password for the server connection.
- **verbose** (boolean) - Optional - Enable verbose logging.
```

--------------------------------

### Account Properties Log Example

Source: https://github.com/actualbudget/actual/blob/master/packages/sync-server/src/app-gocardless/README.md

Example log output for available account properties when integrating a new institution. This data is useful for filling the `normalizeAccount` function.

```log
Available account properties for new institution integration {
  account: '{
    "iban": "PL00000000000000000987654321",
    "currency": "PLN",
    "ownerName": "John Example",
    "displayName": "Product name",
    "product": "Daily account",
    "usage": "PRIV",
    "ownerAddressUnstructured": [
      "POL",
      "UL. Example 1",
      "00-000 Warsaw"
    ],
    "id": "XXXXXXXX-XXXX-XXXXX-XXXXXX-XXXXXXXXX",
    "created": "2023-01-18T12:15:16.502446Z",
    "last_accessed": null,
    "institution_id": "MBANK_RETAIL_BREXPLPW",
    "status": "READY",
    "owner_name": "",
    "institution": {
      "id": "MBANK_RETAIL_BREXPLPW",
      "name": "mBank Retail",
      "bic": "BREXPLPW",
      "transaction_total_days": "90",
      "countries": [
        "PL"
      ],
      "logo": "https://cdn.nordigen.com/ais/MBANK_RETAIL_BREXPLPW.png",
      "supported_payments": {},
      "supported_features": [
        "access_scopes",
        "business_accounts",
        "card_accounts",
        "corporate_accounts",
        "pending_transactions",
        "private_accounts"
      ]
    }
  }'
}
```

--------------------------------

### Navigate into Actual Server Directory

Source: https://github.com/actualbudget/actual/wiki/Fly.io-git

Moves into the newly cloned 'actual-server' directory.

```cmd
cd actual-server
```

--------------------------------

### Transactions Properties Log Example for Sorting

Source: https://github.com/actualbudget/actual/blob/master/packages/sync-server/src/app-gocardless/README.md

Example log output for the first 10 transactions, useful for implementing the `sortTransactions` function. It shows available properties like transaction ID, dates, amounts, and names.

```log
Available (first 10) transactions properties for new integration of institution in sortTransactions function
{
  top10SortedTransactions: '[
    {
      "transactionId": "20220101001",
      "bookingDate": "2022-01-01",
      "valueDate": "2022-01-01",
      "transactionAmount": {
        "amount": "5.01",
        "currency": "EUR"
      },
      "creditorName": "JOHN EXAMPLE",
      "creditorAccount": {
        "iban": "PL00000000000000000987654321"
      },
      "debtorName": "CHRIS EXAMPLE",
      "debtorAccount": {
        "iban": "PL12345000000000000987654321"
      },
      "remittanceInformationUnstructured": "TEST BANK TRANSFER",
      "remittanceInformationUnstructuredArray": [
        "TEST BANK TRANSFER"
      ],
      "balanceAfterTransaction": {
        "balanceAmount": {
          "amount": "448.52",
          "currency": "EUR"
        },
        "balanceType": "interimBooked"
      },
      "internalTransactionId": "casfib7720c2a02c0331cw2"
    }
  ]'
```

--------------------------------

### Initialize Terraform

Source: https://github.com/actualbudget/actual/wiki/Fly.io-terraform

Initialize Terraform in the 'terraform' directory. This downloads necessary providers and sets up the backend.

```sh
terraform init

```

--------------------------------

### Launch Actual Application

Source: https://github.com/actualbudget/actual/wiki/Fly.io-git

Initiates the deployment process for the Actual application on fly.io. It will detect an existing 'fly.toml' file.

```cmd
flyctl launch
```

--------------------------------

### Get all tags

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/api/reference.md

Retrieves a list of all existing tags.

```js
// Get all tags
let tags = await getTags();
```

--------------------------------

### Get length of text

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/experimental/formulas.md

Returns the number of characters in a text string.

```formula
=LEN(notes)
```

--------------------------------

### Launch Actual app on fly.io

Source: https://github.com/actualbudget/actual/wiki/Fly.io-image

Use this command to launch the Actual app, specifying the container image. Follow the prompts to configure the app name, region, and database setup.

```sh
fly launch --image jlongster/actual-server:latest
```

--------------------------------

### Define a Category Group Object

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/api/reference.md

Example structure for a category group object.

```js
{
  name: 'Bills';
}
```

--------------------------------

### Navigate to directory

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/install/fly.md

Example command for changing the current working directory in a terminal.

```bash
cd
```

--------------------------------

### Build the server

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/actual-server-repo-move.md

Command to compile the server code.

```bash
yarn build:server
```

--------------------------------

### Build Static Documentation

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/README.md

Generates static content for the documentation site into the 'build' directory, ready for hosting.

```bash
$ yarn build
```

--------------------------------

### Define a rule object

Source: https://github.com/actualbudget/actual/blob/master/packages/docs/docs/api/reference.md

Example structure of a rule object containing conditions and actions.

```js
{
  stage: 'pre',
  conditionsOp: 'and',
  conditions: [
    {
      field: 'payee',
      op: 'is',
      value: 'test-payee',
    },
  ],
  actions: [
    {
      op: 'set',
      field: 'category',
      value: 'fc3825fd-b982-4b72-b768-5b30844cf832',
    },
  ],
}
```