Welcome to YNAB CLI

This is a simple cli/tui application written in python to help manage your YNAB data.

Requirements

uv which allows you to easily run python applications.
Your YNAB developer access token.

Warning

Developer access tokens are rate limited to 200 requests per hour. Some of the commands below will provide you an opportunity to enter a new developer access token when the current one has exceeded it's limit. It also seems like there is a limit to how many developer access tokens you can create from the developer settings UI.

Your YNAB budget ID. Once you have uv and your access token you can list your budgets by running:

$ uvx ynab-cli run --access-token your_access_token budgets list-all

Usage

Note

YNAB CLI supports environment variables and dotenv (.env) files for specifying options. See the .env-sample file for some examples. YNAB CLI looks for the .env file in current working directory. If you create a .env file with the following information you won't need to keep entering it on the command line.

.env

YNAB_CLI_ACCESS_TOKEN=your_access_token
YNAB_CLI_BUDGET_ID=your_budget_id

To run the text ui, execute the following command:

$ uvx ynab-cli

The individual CLI commands can be similarily run using uvx. Full command line usage is below.

ynab-cli

Main entrypoint.

Usage:

ynab-cli [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--dry-run`	boolean	Run without making any changes.	`False`
`--debug`	boolean	Enable debug mode for more verbose output.	`False`
`--version`	boolean	Show the version and exit.	`False`
`--help`	boolean	Show this message and exit.	`False`

Subcommands

run: Main entrypoint for YNAB CLI commands.
tui: Run the Textual User Interface (TUI) for YNAB CLI.

ynab-cli run

Main entrypoint for YNAB CLI commands.

Usage:

ynab-cli run [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--access-token`	text	YNAB API access token.	None
`--help`	boolean	Show this message and exit.	`False`

Subcommands

budgets: Manage YNAB budgets in YNAB.
categories: Manage YNAB categories in the YNAB budget.
payees: Manage payees in the YNAB budget.
transactions: Manage transactions in the YNAB budget.

ynab-cli run budgets

Manage YNAB budgets in YNAB.

Usage:

ynab-cli run budgets [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

Subcommands

list-all: List all budgets in YNAB.

ynab-cli run budgets list-all

List all budgets in YNAB.

Usage:

ynab-cli run budgets list-all [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

ynab-cli run categories

Manage YNAB categories in the YNAB budget.

Usage:

ynab-cli run categories [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--budget-id`	text	YNAB budget ID.	None
`--help`	boolean	Show this message and exit.	`False`

Subcommands

list-all: List all categories in the YNAB budget.
list-unused: List unused categories in the YNAB budget.

List all categories in the YNAB budget.

Usage:

ynab-cli run categories list-all [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

List unused categories in the YNAB budget.

Usage:

ynab-cli run categories list-unused [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

ynab-cli run payees

Manage payees in the YNAB budget.

Usage:

ynab-cli run payees [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--budget-id`	text	YNAB budget ID.	None
`--help`	boolean	Show this message and exit.	`False`

Subcommands

list-all: List all payees in the YNAB budget.
list-duplicates: List duplicate payees in the YNAB budget.
list-unused: List unused payees in the YNAB budget.
normalize-names: Normalize payee names in the YNAB budget.

ynab-cli run payees list-all

List all payees in the YNAB budget.

Usage:

ynab-cli run payees list-all [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

ynab-cli run payees list-duplicates

List duplicate payees in the YNAB budget.

Usage:

ynab-cli run payees list-duplicates [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

ynab-cli run payees list-unused

List unused payees in the YNAB budget.

Usage:

ynab-cli run payees list-unused [OPTIONS]

Options:

Name	Type	Description	Default
`--prefix-unused`	boolean	Add a prefix to the unused payee names.	`False`
`--help`	boolean	Show this message and exit.	`False`

ynab-cli run payees normalize-names

Normalize payee names in the YNAB budget.

Usage:

ynab-cli run payees normalize-names [OPTIONS]

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

ynab-cli run transactions

Manage transactions in the YNAB budget.

Usage:

ynab-cli run transactions [OPTIONS] COMMAND [ARGS]...

Options:

Name	Type	Description	Default
`--budget-id`	text	YNAB budget ID.	None
`--help`	boolean	Show this message and exit.	`False`

Subcommands

apply-rules: Apply transaction rules from a JSON RULES_FILE to transactions in the YNAB budget.

ynab-cli run transactions apply-rules

Apply transaction rules from a JSON RULES_FILE to transactions in the YNAB budget.

RULES_FILE should be a JSON file containing transaction rules.

Usage:

ynab-cli run transactions apply-rules [OPTIONS] RULES_FILE

Options:

Name	Type	Description	Default
`--help`	boolean	Show this message and exit.	`False`

ynab-cli tui

Run the Textual User Interface (TUI) for YNAB CLI.

Usage:

ynab-cli tui [OPTIONS]

Options:

Name	Type	Description	Default
`--access-token`	text	YNAB API access token.	``
`--budget-id`	text	YNAB budget ID.	``
`--help`	boolean	Show this message and exit.	`False`