ezBookkeeping

https://ezbookkeeping.mayswind.net/
Admin
ezBookkeeping is an open-source, lightweight, self-hosted personal finance application with...
Tokens:36,543
Snippets:390
Trust Score:6.2
Update:6 months ago
Show doc for...
Tokens:
Raw
### Run ezBookkeeping Server

Source: https://ezbookkeeping.mayswind.net/installation/installation-binary

Execute the binary to start the server on the default port 8080.

```shell
$ ./ezbookkeeping server run
```

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

### Manage ezBookkeeping with systemd

Source: https://ezbookkeeping.mayswind.net/installation/installation-binary

Commands to start the service and enable it for automatic startup on boot.

```shell
$ systemctl start ezbookkeeping
```

```shell
$ systemctl enable ezbookkeeping
```

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

### Backend Language File Structure

Source: https://ezbookkeeping.mayswind.net/zh_Hans/translating

Example of a backend language Go file. Ensure all text entries are translated.

```go
package locales

// en is the English language
var en = map[string]string{
	"common.cancel": "Cancel",
	"common.save": "Save",
	"pages.home.welcomeMessage": "Welcome to ezBookkeeping!",
}
```

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

### Install ezBookkeeping Skill via CLI

Source: https://ezbookkeeping.mayswind.net/agent/openclaw

Use the ClawHub CLI to install the ezBookkeeping skill directly.

```shell
npx clawhub@latest install ezbookkeeping
```

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

### Install and Run ezBookkeeping from Binary (Windows)

Source: https://ezbookkeeping.mayswind.net/installation

After downloading the latest release binary for Windows, use this command to run the ezBookkeeping server. It defaults to port 8080.

```powershell
> .\ezbookkeeping.exe server run
```

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

### Install Agent Skill via CLI

Source: https://ezbookkeeping.mayswind.net/agent/skill

Use the Skills CLI to add the ezBookkeeping skill to your environment.

```shell
npx skills add mayswind/ezbookkeeping@ezbookkeeping
```

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

### Frontend Language File Structure

Source: https://ezbookkeeping.mayswind.net/zh_Hans/translating

Example of a frontend language JSON file. Ensure all text entries are translated.

```json
{
  "name": "English",
  "displayName": "English",
  "alternativeLanguageTag": "en-US",
  "textDirection": "ltr",
  "content": {
    "common": {
      "cancel": "Cancel",
      "save": "Save"
    },
    "pages": {
      "home": {
        "welcomeMessage": "Welcome to ezBookkeeping!"
      }
    }
  }
}
```

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

### Run ezBookkeeping with Docker (Latest Release)

Source: https://ezbookkeeping.mayswind.net/installation

Use this command to run the latest stable release of ezBookkeeping using Docker. Ensure Docker is installed.

```shell
$ docker run -p8080:8080 mayswind/ezbookkeeping
```

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

### Run ezBookkeeping Docker Image

Source: https://ezbookkeeping.mayswind.net/installation/installation-docker

Starts the ezBookkeeping container in detached mode, mapping host port 8080 to container port 8080. The container will use default configurations.

```shell
$ docker run -d -p8080:8080 --name ezbookkeeping mayswind/ezbookkeeping
```

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

### Prepare Host Directories for Mounting

Source: https://ezbookkeeping.mayswind.net/installation/installation-docker

Creates directories on the host machine for ezBookkeeping data and storage, and sets their ownership to UID/GID 1000. This is necessary before mounting them into the container.

```shell
# Create data directory and modify UID/GID in host
$ mkdir -p /var/lib/ezbookkeeping/data
$ mkdir -p /var/lib/ezbookkeeping/storage
$ chown 1000:1000 /var/lib/ezbookkeeping/data
$ chown 1000:1000 /var/lib/ezbookkeeping/storage
```

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

### GET accounts/list.json

Source: https://ezbookkeeping.mayswind.net/httpapi/account_api

Retrieves a list of all account information.

```APIDOC
## GET accounts/list.json

### Description
Retrieves all account information for the user.

### Method
GET

### Endpoint
accounts/list.json

### Response
#### Success Response (200)
- **AccountInfoResponse[]** (array) - A list of account objects.
```

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

### GET /transaction/tags/list.json

Source: https://ezbookkeeping.mayswind.net/httpapi/transaction_tag_api

Retrieves a list of all available transaction tags.

```APIDOC
## GET /transaction/tags/list.json

### Description
Retrieves all available transaction tags.

### Method
GET

### Endpoint
transaction/tags/list.json

### Response
#### Success Response (200)
- **id** (string) - Transaction tag ID
- **name** (string) - Transaction tag name
- **groupId** (string) - Transaction tag group ID
- **displayOrder** (integer) - The display order of the transaction tag
- **hidden** (boolean) - Whether the transaction tag is hidden

#### Response Example
[
  {
    "id": "1",
    "name": "Work",
    "groupId": "0",
    "displayOrder": 1,
    "hidden": false
  }
]
```

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

### GET tokens/list.json

Source: https://ezbookkeeping.mayswind.net/httpapi/token_api

Retrieves a list of all available session information for the current user.

```APIDOC
## GET tokens/list.json

### Description
Retrieves all available session information.

### Method
GET

### Endpoint
tokens/list.json

### Response
#### Success Response (200)
- **tokenId** (string) - Token ID
- **tokenType** (integer) - Token type (1: Normal Token, 5: MCP Token, 8: API Token)
- **userAgent** (string) - The User Agent when the session created
- **lastSeen** (integer) - Last refresh unix time of the session
- **isCurrent** (boolean) - Whether the session is current
```

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

### Build Frontend Files (Windows)

Source: https://ezbookkeeping.mayswind.net/developing

Builds the frontend files for Windows. The output will be placed in the 'dist' directory.

```batch
> .\build.bat frontend
```

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

### Run ezBookkeeping with Docker (Latest Daily Build)

Source: https://ezbookkeeping.mayswind.net/installation

Use this command to run the latest daily snapshot build of ezBookkeeping using Docker. This is useful for testing the most recent changes.

```shell
$ docker run -p8080:8080 mayswind/ezbookkeeping:latest-snapshot
```

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

### Build Backend File (Windows)

Source: https://ezbookkeeping.mayswind.net/developing

Builds the backend executable for Windows. The output file will be named 'ezbookkeeping'.

```batch
> .\build.bat backend
```

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

### Build Backend File (Linux/macOS)

Source: https://ezbookkeeping.mayswind.net/developing

Builds the backend executable for Linux or macOS. The output file will be named 'ezbookkeeping'.

```shell
$ ./build.sh backend
```

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

### Build Full Package (Windows)

Source: https://ezbookkeeping.mayswind.net/developing

Builds and packages all project files into a zip archive for Windows.

```batch
> .\build.bat package -o ezbookkeeping.zip
```

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

### GET exchange_rates/latest.json

Source: https://ezbookkeeping.mayswind.net/httpapi/exchange_rate_api

Retrieves the latest exchange rate data including the data source, update time, base currency, and a list of exchange rates.

```APIDOC
## GET exchange_rates/latest.json

### Description
Retrieves the latest exchange rate data including the data source, update time, base currency, and a list of exchange rates.

### Method
GET

### Endpoint
exchange_rates/latest.json

### Response
#### Success Response (200)
- **dataSource** (string) - Exchange rate data source name
- **referenceUrl** (string) - Exchange rate data reference URL
- **updateTime** (integer) - Exchange rate data update unix time
- **baseCurrency** (string) - Base currency code
- **exchangeRates** (LatestExchangeRate[]) - List of exchange rates

#### Data Structure: LatestExchangeRate
- **currency** (string) - Currency code
- **rate** (string) - Exchange rate, 1 unit of base currency equals to how many units of this currency
```

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

### GET /transactions/list/all.json

Source: https://ezbookkeeping.mayswind.net/httpapi/transaction_api

Retrieves all transaction data matching the specified query criteria. Supports filtering by type, category, account, tags, amount, keyword, time range, and inclusion of pictures.

```APIDOC
## GET /transactions/list/all.json

### Description
Retrieves all transaction data matching the specified query criteria. Supports filtering by type, category, account, tags, amount, keyword, time range, and inclusion of pictures.

### Method
GET

### Endpoint
`/transactions/list/all.json`

### Request Header
- **X-Timezone-Name** (string) - IANA time zone name
- **X-Timezone-Offset** (integer) - Time zone offset (minutes)

### Query Parameters
- **type** (integer) - Optional - Filter transaction by transaction type (`1`: Balance modification, `2`: Income, `3`: Expense, `4`: Transafer)
- **category_ids** (string) - Optional - Filter transaction by transaction category IDs (separated by `,`)
- **account_ids** (string) - Optional - Filter transaction by account IDs (separated by `,`)
- **tag_filter** (string) - Optional - Filter transactions by tags (multiple tag groups are supported, separate groups with `;`. Each tag group uses the format `type:tag_id1,tag_id2,...` where `type` defines the filter mode, `0`: transaction contains all tags in the group, `1`: transaction contains any tag in the group, `2`: transaction does not contain all tags in the group, `3`: transaction does not contain any tag in the group)
- **amount_filter** (string) - Optional - Filter transaction by amount (Supports up to two decimals. For example, a value of `1234` represents an amount of `12.34`. Greater than amount: `gt:{amount}`, Less than amount: `lt:{amount}`, Equal amount: `eq:{amount}`, Not equal amount: `ne:{amount}`, Between two amounts: `bt:{min_amount}:{max_amount}`, Not between two amounts: `ne:{min_amount}:{max_amount}`)
- **keyword** (string) - Optional - Filter transaction by keyword
- **start_time** (integer) - Optional - Transaction list start time (unix time)
- **end_time** (integer) - Optional - Transaction list end time (unix time)
- **with_pictures** (boolean) - Optional - Whether to get the picture IDs
- **trim_account** (boolean) - Optional - Whether to get the account ID instead of account object
- **trim_category** (boolean) - Optional - Whether to get the transaction category ID instead of category object
- **trim_tag** (boolean) - Optional - Whether to get the tag IDs instead of tag object

### Response
#### Success Response (200)
- **TransactionInfoResponse[]** (array) - An array of transaction information objects.
```

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

### Build Docker Image (Linux)

Source: https://ezbookkeeping.mayswind.net/developing

Builds a Docker image for ezBookkeeping and tags it as 'ezbookkeeping:release'.

```shell
$ ./build.sh docker -t ezbookkeeping:release
```

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

### Download and Make ezBookkeeping API Tools Executable (Linux/macOS)

Source: https://ezbookkeeping.mayswind.net/httpapi

Download the API tool script and make it executable. This script simplifies calling API endpoints from the command line.

```shell
$ curl https://raw.githubusercontent.com/mayswind/ezbookkeeping/refs/heads/main/skills/ezbookkeeping/scripts/ebktools.sh -o ebktools.sh
$ chmod +x ebktools.sh
```

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

### Build Full Package (Linux/macOS)

Source: https://ezbookkeeping.mayswind.net/developing

Builds and packages all project files into a tar.gz archive for Linux or macOS.

```shell
$ ./build.sh package -o ezbookkeeping.tar.gz
```

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

### Configure API Tool Environment Variables

Source: https://ezbookkeeping.mayswind.net/agent/skill

Define the server base URL and API token in a .env file to authenticate and connect the agent to the ezBookkeeping server.

```text
EBKTOOL_SERVER_BASEURL="https://{YOUR_HOST_ADDRESS}"
EBKTOOL_TOKEN="{YOUR-API-TOKEN}"
```

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

### Run ezBookkeeping API Tools (Linux/macOS)

Source: https://ezbookkeeping.mayswind.net/httpapi

Execute the API tools script after configuring the environment variables. This allows for command-line interaction with the ezBookkeeping API.

```shell
$ ./ebktools.sh
```

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

### View Skill Directory Structure

Source: https://ezbookkeeping.mayswind.net/agent/skill

The expected file structure after downloading the skill components from the GitHub repository.

```text
.
├── ezbookkeeping
│   ├── SKILL.md
│   └── scripts
│       ├── ebktools.ps1
│       └── ebktools.sh
```

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

### Build ezBookkeeping Docker Image (Linux)

Source: https://ezbookkeeping.mayswind.net/installation

Builds a Docker image for ezBookkeeping from source on Linux. Requires Docker and the build scripts. This command initiates the Docker image creation process.

```shell
$ ./build.sh docker
```

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

### Build Frontend Files (Linux/macOS)

Source: https://ezbookkeeping.mayswind.net/developing

Builds the frontend files for Linux or macOS. The output will be placed in the 'dist' directory.

```shell
$ ./build.sh frontend
```

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

### Build Backend File (PowerShell)

Source: https://ezbookkeeping.mayswind.net/developing

Builds the backend executable using PowerShell. The output file will be named 'ezbookkeeping'.

```powershell
PS > .\build.ps1 backend
```

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

### Add new language for backend

Source: https://ezbookkeeping.mayswind.net/translating

For the backend, copy the English Go file, create a new file with the language tag, and add a key-value pair to the `AllLanguages` map in `/pkg/locales/all_locales.go`. The `Content` field within the value object should contain the new language object.

```go
var AllLanguages = map[string]Language{
	"en": {
		Content: en,
	},
	// Add new language here
};
```

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

### Build Full Package (PowerShell)

Source: https://ezbookkeeping.mayswind.net/developing

Builds and packages all project files into a zip archive using PowerShell.

```powershell
PS > .\build.ps1 package -Output ezbookkeeping.zip
```

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

### Build Frontend Files (PowerShell)

Source: https://ezbookkeeping.mayswind.net/developing

Builds the frontend files using PowerShell. The output will be placed in the 'dist' directory.

```powershell
PS > .\build.ps1 frontend
```

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

### Backend Language Registration

Source: https://ezbookkeeping.mayswind.net/zh_Hans/translating

Register a new language in `/pkg/locales/all_locales.go` by adding an entry to the `AllLanguages` map. The key is the language tag, and the value is a struct containing the language content.

```go
package locales

// AllLanguages is a map of all available languages.
var AllLanguages = map[string]Language{
	"en": {
		Content: en,
	},
	// Add other languages here
}
```

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

### Apply Kubernetes Manifests

Source: https://ezbookkeeping.mayswind.net/installation/installation-kubernetes

Commands to deploy the secret, application, and ingress resources to the cluster.

```shell
kubectl apply -f secret.yaml -n "ezbookkeeping"
kubectl apply -f ezbookkeeping.yaml -n "ezbookkeeping"
kubectl apply -f ingress.yaml -n "ezbookkeeping"
```

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

### ezBookkeeping Command Line Usage

Source: https://ezbookkeeping.mayswind.net/command_line

General syntax for using the ezBookkeeping command line tool. Specify global options, a command, and command-specific options or arguments.

```shell
ezbookkeeping [global options] command [command options] [arguments...]
```

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

### Run Container with Mounted Host Paths

Source: https://ezbookkeeping.mayswind.net/installation/installation-docker

Runs the ezBookkeeping container, mounting host directories into the container for data and storage. This provides persistent storage using the host's file system.

```shell
# Run container with mounting host path
$ docker run -d -p8080:8080 --name ezbookkeeping -v /var/lib/ezbookkeeping/data:/ezbookkeeping/data -v /var/lib/ezbookkeeping/storage:/ezbookkeeping/storage mayswind/ezbookkeeping
```

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

### Configure ezBookkeeping API Tools Environment Variables (Linux/macOS)

Source: https://ezbookkeeping.mayswind.net/httpapi

Set the server base URL and API token as environment variables for the API tools script. Alternatively, these can be placed in a .env file.

```shell
$ export EBKTOOL_SERVER_BASEURL="https://{YOUR_HOST_ADDRESS}"
$ export EBKTOOL_TOKEN="{YOUR-API-TOKEN}"
```

```dotenv
EBKTOOL_SERVER_BASEURL="https://{YOUR_HOST_ADDRESS}"
EBKTOOL_TOKEN="{YOUR-API-TOKEN}"
```

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

### Download ezBookkeeping API Tools Script (Windows PowerShell)

Source: https://ezbookkeeping.mayswind.net/httpapi

Download the PowerShell script for interacting with the ezBookkeeping API. This script requires PowerShell and specific command-line tools.

```powershell
PS > Invoke-WebRequest -Uri https://raw.githubusercontent.com/mayswind/ezbookkeeping/refs/heads/main/skills/ezbookkeeping/scripts/ebktools.ps1 -OutFile .\ebktools.ps1
```

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

### POST accounts/add.json

Source: https://ezbookkeeping.mayswind.net/httpapi/account_api

Adds a new account to the system.

```APIDOC
## POST accounts/add.json

### Description
Creates a new account with the provided details.

### Method
POST

### Endpoint
accounts/add.json

### Parameters
#### Request Header
- **X-Timezone-Name** (string) - Required - IANA time zone name
- **X-Timezone-Offset** (integer) - Required - Time zone offset (minutes)

#### Request Body
- **name** (string) - Required - Account name
- **category** (AccountCategory) - Required - Account category
- **type** (AccountType) - Required - Account type
- **icon** (string) - Required - Account icon ID
- **color** (string) - Required - Account icon color (Hex color code RRGGBB)
- **currency** (string) - Required - Account currency code (ISO 4217 code)
- **balance** (integer) - Optional - Account balance (up to two decimals)
- **balanceTime** (integer) - Optional - Unix time when the account balance is the set value
- **comment** (string) - Optional - Account description
- **creditCardStatementDate** (integer) - Optional - The statement date of the credit card account
- **subAccounts** (AccountCreateRequest[]) - Optional - The sub accounts list

### Response
#### Success Response (200)
- **AccountInfoResponse** (object) - The created account object.
```
Tokens:
Raw