ezBookkeeping Documentation

The API tools require two specific environment variables to function. If they are not set in your system environment, you can create a .env file in your user home directory containing these variables.

To build ezBookkeeping from source, ensure you have Golang, GCC, Node.js, and NPM installed.

Package the application

Use the provided build scripts to package the application into a compressed archive.

Build a Docker image

If you have Docker installed, you can build a custom Docker image from the source.

The ezbookkeeping API Tools scripts allow you to interact with the ezBookkeeping server to record transactions, query data, retrieve account information, categories, tags, and exchange rate data.

Depending on your operating system, use the shell script (.sh) for Linux/macOS or the PowerShell script (.ps1) for Windows.

You can run ezBookkeeping directly from a downloaded binary. First, download the appropriate release for your operating system from the GitHub Releases page.

Once downloaded, use the server run command to start the application. By default, it listens on port 8080.

You can discover available commands and view specific help documentation using the following commands:

List all supported commands:

• Linux/macOS: sh scripts/ebktools.sh list
• Windows: scripts\ebktools.ps1 list

Show help for a specific command:

• Linux/macOS: sh scripts/ebktools.sh help <command>
• Windows: scripts\ebktools.ps1 help <command>

The fastest way to deploy ezBookkeeping is using Docker. You can run the latest stable release or the latest daily build (snapshot).

To run the latest stable release, map port 8080 of the container to port 8080 on your host. After starting, access the application at http://{YOUR_HOST_ADDRESS}:8080/.

The following language tags are currently supported for translation:

The UserDataCli provides several methods for administrative user management through the CLI. Key tasks include:

• Add a new user: Create a user with a username, email, nickname, password, and default currency.
• Retrieve user: Get user details by their username.
• Modify password: Update a user's password and automatically revoke their existing tokens.
• Account status: Enable or disable user accounts.
• Email verification: Resend account activation emails or manually set a user's email as verified/unverified.
• Password reset: Trigger a password reset email to a user.
• Delete user: Remove a user from the system.
• Feature restrictions: Add, remove, or set specific feature restrictions for a user.

Tools for maintaining the consistency of a user's financial data:

• Check transaction and account integrity: Validates that all transactions correctly reference existing accounts and categories, checks that sub-accounts and sub-categories are used correctly, and verifies that the calculated account balances match the stored balances.
• Fix transaction tag index: Repairs transaction tag index data by synchronizing the TransactionTime from the transaction record to the tag index if it is missing or invalid.

The UserDataCli supports data portability for user transactions:

• Export transactions: Export all transactions for a user into a specific file format (e.g., CSV) as a byte array.
• Import transactions: Import transactions from a file.

Important Import Note: The import process will fail if the data contains new accounts, categories (expense, income, or transfer), or tags that do not already exist in the user's data. You must create these entities manually before importing the transaction data.

Administrative functions for managing security tokens and Two-Factor Authentication (2FA) for specific users:

• List user tokens: Retrieve all unexpired normal and MCP tokens for a specific user.
• Create user token: Generate a new api or mcp token for a user. You can specify the expiresInSeconds.
• Revoke user token: Revoke a specific token using its string value.
• Clear user tokens: Revoke all existing tokens for a user.
• Disable 2FA: Disable Two-Factor Authentication for a user and delete their recovery codes.