### Clone and Install Dependencies (Git, Yarn)

Source: https://actualbudget.org/docs/contributing/development-setup

Clones the Actual Budget repository using Git and installs all project dependencies using Yarn. This is the first step in setting up the development environment.

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

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

### Run Specific Workspace Commands Examples (Yarn)

Source: https://actualbudget.org/docs/contributing/development-setup

Provides examples of running commands for specific workspaces, such as running tests for 'loot-core', starting the docs development server, or building the '@actual-app/api' package.

```bash
yarn workspace loot-core run test
yarn workspace docs start
yarn workspace @actual-app/api build
```

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

### Start Development Servers (Yarn)

Source: https://actualbudget.org/docs/contributing/development-setup

Starts various development servers for the Actual Budget project. This includes the browser development server, a server for testing sync functionality, and the desktop app development server.

```bash
yarn start
yarn start:browser
yarn start:server-dev
yarn start:desktop
```

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

### Build Project Versions (Yarn)

Source: https://actualbudget.org/docs/contributing/development-setup

Builds different versions of the Actual Budget project, including the browser version, the desktop application, the API package, and the sync server.

```bash
yarn build:browser
yarn build:desktop
yarn build:api
yarn build:server
```

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

### Enable and Start Actual Server Service

Source: https://actualbudget.org/docs/install/build-from-source

Enables the Actual server service to start on system boot and starts it immediately. This command integrates the Actual server with the system's service management.

```bash
systemctl enable --now /etc/systemd/system/multi-user.target.wants/actual-server.service
```

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

### Install Server Dependencies with Yarn

Source: https://actualbudget.org/docs/actual-server-repo-move

This command uses Yarn to install all the necessary project dependencies for the Actual server. It should be run after navigating to the project root. Ensure Yarn is installed.

```bash
yarn install
```

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

### Start Actual Server Service

Source: https://actualbudget.org/docs/install/build-from-source

Starts the Actual server service if it is not already running. This command is used to launch the server manually.

```bash
systemctl start actual-server
```

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

### Install Actual Budget CLI Tool Globally

Source: https://actualbudget.org/docs/install/cli-tool

Installs the Actual sync-server CLI tool globally using npm. Node.js v22 or higher is required. This command makes the `actual-server` executable available in your terminal.

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

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

### Launch Docker Compose Container

Source: https://actualbudget.org/docs/install/docker

Launches the latest stable version of the Actual Budget server using Docker Compose. Ensure Docker is installed. This command creates and starts the container in detached mode.

```bash
docker compose up --detach
```

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

### Install Fly.io CLI on Windows

Source: https://actualbudget.org/docs/install/fly

Installs the Fly.io command-line tool on Windows using PowerShell. This command downloads and executes an installation script. Ensure you have PowerShell open and paste the command directly.

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

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

### Average Template Examples

Source: https://actualbudget.org/docs/experimental/goal-templates

Illustrates how the Average template calculates budgeted amounts based on past spending and adjustments. Shows examples with percentage and fixed number adjustments.

```budgeting
Template line| Budgeted Amount
---|---
`#template average 3 months`| $ 50
`#template average 3 months [increase 20%]`| $ 60
`#template average 3 months [decrease 10%]`| $ 45
`#template average 3 months [increase 11]`| $ 61
`#template average 3 months [decrease 1]`| $ 49
```

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

### Install Fly.io CLI on macOS/Linux

Source: https://actualbudget.org/docs/install/fly

Installs the Fly.io command-line tool on macOS and Linux systems using a shell script. This command downloads and executes the installation script. Note that on macOS, you might need to use `~/.fly/bin/fly` if the `fly` command is not found.

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

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

### Install Actual API Package with npm

Source: https://actualbudget.org/docs/api

Installs the official Node.js client for Actual API using npm. This package provides programmatic access to your budget data.

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

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

### Create Rule Example

Source: https://actualbudget.org/docs/api/reference

An example of a rule object used for creating or updating rules. It includes conditions and actions to be performed.

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

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

### Install Yarn Package Manager

Source: https://actualbudget.org/docs/install/build-from-source

Installs the Yarn package manager globally using npm. This is a prerequisite for managing Actual's dependencies.

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

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

### Basic ActualQL Query Syntax Example

Source: https://actualbudget.org/docs/api/actual-ql

Provides a fundamental example of ActualQL syntax, showcasing the chaining of methods to construct a query. This query targets the 'transactions' table, filters by category and date, and selects specific fields.

```plaintext
q('transactions')
  .filter({
    'category.name': 'Food',
    date: '2021-02-20',
  })
  .select(['id', 'date', 'amount']);
```

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

### Install Actual API Package with yarn

Source: https://actualbudget.org/docs/api

Installs the official Node.js client for Actual API using yarn. This package provides programmatic access to your budget data.

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

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

### Configure Cost Optimizations for Actual Budget

Source: https://actualbudget.org/docs/install/fly

This TOML configuration snippet enables automatic stopping and starting of machines for Actual Budget to reduce compute costs. It introduces a potential delay of 5-15 seconds when starting the application after a period of inactivity. This configuration should be added to your services section and requires re-deployment.

```toml
[[services]]
  auto_stop_machines = "stop"
  auto_start_machines = true
  min_machines_running = 0
```

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

### Actual Budget CLI Tool Examples

Source: https://actualbudget.org/docs/install/cli-tool

Demonstrates different ways to run the Actual sync-server CLI tool, including using default configuration, a custom JSON configuration file, and environment variables for configuration.

```bash
actual-server
```

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

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

```bash
actual-server --reset-password
```

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

### Clean Build Artifacts and Reinstall Dependencies (Bash, Yarn)

Source: https://actualbudget.org/docs/contributing/development-setup

Removes build artifacts from various packages and then reinstalls all project dependencies. This is a common troubleshooting step for build or installation issues.

```bash
rm -rf packages/*/dist packages/*/lib-dist packages/*/build
yarn install
```

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

### Run Workspace-Specific Commands (Yarn)

Source: https://actualbudget.org/docs/contributing/development-setup

Executes commands for a specific workspace within the Yarn monorepo. This allows for targeted operations on individual packages.

```bash
yarn workspace <workspace-name> run <command>
```

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

### Run the Actual Server with Yarn

Source: https://actualbudget.org/docs/actual-server-repo-move

This command starts the Actual server using Yarn. It executes the built server code, making the sync server operational. This is the final step for users building from source.

```bash
yarn start:server
```

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

### Lint and Format Code (Yarn)

Source: https://actualbudget.org/docs/contributing/development-setup

Checks for linting and formatting issues in the codebase using Yarn. The `lint:fix` command attempts to automatically resolve these issues.

```bash
yarn lint
yarn lint:fix
```

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

### Run Tests (Yarn)

Source: https://actualbudget.org/docs/contributing/development-setup

Executes all tests across all packages in the Actual Budget monorepo. The `test:debug` command runs tests without using the cache, which is useful for debugging.

```bash
yarn test
yarn test:debug
```

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

### Run TypeScript Type Checking (Yarn)

Source: https://actualbudget.org/docs/contributing/development-setup

Executes TypeScript type checking across all packages in the monorepo. This command is crucial for ensuring code quality and should be run before committing changes.

```bash
yarn typecheck
```

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

### Navigate to Desktop Client Directory

Source: https://actualbudget.org/docs/install/build-from-source

These commands are used to navigate to the specific directory within the Actual project where the desktop client's localization files are managed. This is a prerequisite for cloning the translations repository.

```bash
cd actual
cd packages/desktop-client
```

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

### Write Unit Test (TypeScript/Vitest)

Source: https://actualbudget.org/docs/contributing/testing

A basic structure for writing unit tests using Vitest. It demonstrates the use of `describe`, `it`, and `expect` for defining test suites and assertions. `beforeEach` can be used for setup logic before each test.

```typescript
import { describe, it, expect, beforeEach } from 'vitest';
// ... other imports

describe('ComponentName', () => {
  beforeEach(() => {
    // Setup code
  });

  it('should behave as expected', () => {
    // Test logic
    expect(result).toBe(expected);
  });
});
```

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

### Initialization and Shutdown

Source: https://actualbudget.org/docs/api/reference

Methods for initializing the API connection to an Actual Budget server and shutting down the API gracefully.

```APIDOC
## POST /init

### Description
Initializes the API by connecting to an Actual Budget server.

### Method
POST

### Endpoint
/init

### Parameters
#### Request Body
- **config** (InitConfig) - Required - Configuration object for the Actual Budget server.
  - **serverURL** (string) - Optional - The URL of your Actual Budget server.
  - **password** (string) - Optional - The password of your Actual Budget server.
  - **dataDir** (string) - Optional - The directory to store locally cached budget files.
  - **verbose** (boolean) - Optional - Enable/disable logging from actual internals

### Response
#### Success Response (200)
- **void** - Indicates successful initialization.

## POST /shutdown

### Description
Shuts down the API. This will close any open budget and clean up any resources.

### Method
POST

### Endpoint
/shutdown

### Response
#### Success Response (200)
- **void** - Indicates successful shutdown.
```

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

### Debug E2E Tests (Yarn, Playwright)

Source: https://actualbudget.org/docs/contributing/development-setup

Runs End-to-End (E2E) tests with a headed browser and debugging enabled using Playwright. This is useful for diagnosing issues in the web application's end-to-end flows.

```bash
yarn workspace @actual-app/web run playwright test --headed --debug accounts.test.ts
```

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

### Nginx Server Block Example for Actual Budget with Let's Encrypt SSL

Source: https://actualbudget.org/docs/config/reverse-proxies

This Nginx server block configures SSL using Let's Encrypt certificates and sets up a reverse proxy to the Actual Budget application. It includes essential directives for SSL configuration and proxying, ensuring secure communication. Adapt `server_name` and certificate paths to your specific setup.

```nginx
server {
  listen 443 ssl;
  listen [::]:443 ssl;
  server_name budget.*;

  include /config/nginx/ssl.conf;
  client_max_body_size 0;

  # With SSL via Let's Encrypt
  ssl_certificate /etc/letsencrypt/live/example.com/fullchain.pem; # managed by Certbot
  ssl_certificate_key /etc/letsencrypt/live/example.com/privkey.pem; # managed by Certbot
  include /etc/letsencrypt/options-ssl-nginx.conf; # managed by Certbot
  ssl_dhparam /etc/letsencrypt/ssl-dhparams.pem; # managed by Certbot

  location / {
    include /config/nginx/proxy.conf;
    include /config/nginx/resolver.conf;

    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    proxy_set_header Host $host;

    set $upstream_app actual-server;
    set $upstream_port 5006;
    set $upstream_proto http;
    proxy_pass $upstream_proto://$upstream_app:$upstream_port;
  }
}
```

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

### Construct and Run a Basic ActualQL Query

Source: https://actualbudget.org/docs/api/actual-ql

Demonstrates how to construct a basic ActualQL query for transactions and execute it using `runQuery`. The `q` function initializes a query, and `runQuery` executes it, returning data. The result is an object containing a `data` property, which is an array of transactions.

```javascript
let { q, runQuery } = require('@actual-app/api');

let { data } = await runQuery(q('transactions').select('*'));
```

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

### Connect to Remote Server and Download Budget with Node.js

Source: https://actualbudget.org/docs/api

Connects to a running Actual server, initializes the API client with server details and credentials, downloads a specified budget file, retrieves a specific month's budget data, and then shuts down the API client. It supports both standard and end-to-end encrypted budgets. Consider using environment variables for sensitive information like passwords.

```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();
})();

```