Command-line interface for YNAB.

Version: 0.1.0

You Need A Budget (YNAB) is a personal budgeting app that will help you stop living paycheck to paycheck, get out of debt, and save more money.

This CLI provides access to all functionality exposed by the YNAB API (as of the date of writing). It currently hews very close to the API, without any "porcelain" to provide user-friendly functionality built on top of the API (such features may be added in the future; feel free to suggest one). For now, no data is cached locally.

Features:

Multiple output options. Default is an easy-to-read table, but also supports CSV and JSON for machine-readable output to use in scripts.
Customizable columns. The default selections have the most commonly used columns, but you can have the table or CSV include all values (or fewer) if desired.
Complete. Every API endpoint is supported by the CLI.
Easy to install. Just download an executable and run it (available for Windows/macOS/Linux). No need for Java/Ruby/Python/node.js runtime environment to be installed.
Well documented. The web site describes all commands and configuration.

CLI for YNAB is written by a third party, and is not sponsored, endorsed, or supported by YNAB.

This is an ALPHA release. While basic functionality is there, there are a few missing pieces and there are most certainly bugs. Please report any bugs and panics.

Installation
Initial setup
- Personal access token
- Budget ID
- Other setup
Global arguments
Commands
- ynab create transaction
- ynab get account
- ynab get budget
- ynab get budget-settings
- ynab get category
- ynab get month
- ynab get payee
- ynab get payee-location
- ynab get scheduled-transaction
- ynab get transaction
- ynab get user
- ynab list accounts
- ynab list budgets
- ynab list categories
- ynab list months
- ynab list payee-locations
- ynab list payees
- ynab list scheduled-transactions
- ynab list transactions
- ynab update category
- ynab update transaction
Configuration
Shell completions
Build from source

Installation

Download the appropriate binary for your platform:

Platform	Download link
Linux (64-bit)	cli-for-ynab-0.1.0-x86_64-linux
macOS	cli-for-ynab-0.1.0-x86_64-darwin
Windows (64-bit)	cli-for-ynab-0.1.0-x86_64-windows.exe

If your platform isn't listed, see Build from source.

On Linux/macOS, give the downloaded file execute permissions and put it somewhere on your $PATH with the name ynab. E.g.:

$ chmod a+x /path/to/cli-for-ynab-0.1.0-*
$ sudo cp /path/to/cli-for-ynab-0.1.0-* /usr/local/bin/ynab

On Windows, rename cli-for-ynab-0.1.0-x86_64-windows.exe to ynab.exe and move it to the current directory or somewhere on your %PATH%.

Initial setup

Personal access token

You need a Personal Access Token for the YNAB API to use the CLI. From the YNAB API documentation:

To obtain a Personal Access Token, sign in to your account, go to "My Account", scroll down and navigate to "Developer Settings" section. From the Developer Settings page, click "New Token" under the Personal Access Tokens section, enter your password and you will be presented with a new Personal Access Token. You will not be able to retrieve the token later so you should store it in a safe place. This new token will not expire but can be revoked at any time from this same screen.

Create a text file named .ynab.env in your home directory or the current directory (see Configuration for exact supported paths), containing YNAB_ACCESS_TOKEN=<TOKEN>. For example:

YNAB_ACCESS_TOKEN=4cfb0a3a5f302f2094747e3eeb0690b9112f39f87548f792b0830001232ac1f6

Test the configured credentials by running:

ynab list budgets

If it lists your budgets, then the CLI is configured correctly.

Budget ID

The default budget ID (last-used) will use your most recently used budget. If you want to use a different budget, find its ID from the first column of the ynab list budgets output, and add YNAB_BUDGET_ID=<ID> to .ynab.env. For example, a configuration file with both values:

YNAB_ACCESS_TOKEN=4cfb0a3a5f302f2094747e3eeb0690b9112f39f87548f792b0830001232ac1f6
YNAB_BUDGET_ID=a3a5f302-f209-4747-e3ee-b0690b9112f3

Other setup

See Configuration for more configuration options.

Optionally, you may also want to set up shell auto-completions. See Shell completions for instructions.

Global arguments

These arguments are accepted by all subcommands, and may also appear before the subcommand.

Flags

-h, --help
Prints help information
-V, --version
Prints version information

Options

--access-token <TOKEN>
Personal Access Token for YNAB API. To obtain a Personal Access Token, sign in to your account, go to "My Account", scroll down and navigate to "Developer Settings" section. From the Developer Settings page, click "New Token" under the Personal Access Tokens section, enter your password and you will be presented with a new Personal Access Token. You will not be able to retrieve the token later so you should store it in a safe place. This new token will not expire but can be revoked at any time from this same screen. [env: YNAB_ACCESS_TOKEN=]
--borders <BOOL>
Tables have ASCII borders? [env: YNAB_BORDERS=] [default: false] [possible values: true, false]
--budget-id <UUID>
The id of the budget. last-used can also be used to specify the last used budget. Use ynab get budgets to get a list of your budgets' IDs. [env: YNAB_BUDGET_ID=] [default: last-used]
--headers <BOOL>
Tables have a column headers row? [env: YNAB_HEADERS=] [default: true] [possible values: true, false]
-o, --output <FORMAT>
Output format. If JSON, outputs the response received from the YNAB API directly. [env: YNAB_OUTPUT=] [default: table] [possible values: table, csv, json]

Commands

ynab create transaction

Creates a single transaction or multiple transactions

To create multiple transactions, you must use the --file option. If you provide a body containing a transaction object, a single transaction will be created and if you provide a body containing a transactions array, multiple transactions will be created.

Usage

ynab create transaction [OPTIONS] --set-account-id <UUID> --set-amount <CURRENCY-AMOUNT> --set-date <DATE>

Options

--columns <COLUMN>...
Columns to include in table/CSV output [default: id,account-name,approved,date,payee- name,category-name,memo,amount,cleared] [possible values: all, id, date, amount, memo, cleared, approved, flag-color, account-id, payee- id, category-id, transfer-account-id, transfer-transaction-id, import-id, deleted, type, parent-transaction-id, account-name, payee-name, category-name]
-f, --file <PATH>
If specified, JSON-formatted input containing data to write. The data must match the YNAB API specification (see https://api.youneedabudget.com/v1). Specify - to read from standard input instead of a file.
--set-account-id <UUID>
Set the account ID
--set-amount <CURRENCY-AMOUNT>
If specified, set the transaction amount. [format: match your budget settings' number format (the currency symbol and group separators may be omitted)]
--set-approved <BOOL>
If specified, set whether or not the transaction is approved. If not supplied, transaction will be unapproved by default. [possible values: true, false]
--set-category-id <UUID>
If specified, set the category for the transaction. Split and Credit Card Payment categories are not permitted and will be ignored if supplied. If an existing transaction has a Split category it cannot be changed.
--set-cleared <STATUS>
If specified, set the cleared status of the transaction [possible values: cleared, uncleared, reconciled]
--set-date <DATE>
If specified, set the transaction date. [format: match your budget settings' date format, or ISO 8601 (YYYY-MM-DD) format]
--set-flag-color <COLOR>
If specified, set the transaction flag [possible values: none, red, orange, yellow, green, blue, purple]
--set-import-id <UUID>
If specified, set the import ID. If specified for a new transaction, the transaction will be treated as Imported and assigned this import_id. If another transaction on the same account with this same import_id is later attempted to be created, it will be skipped to prevent duplication. Transactions imported through File Based Import or Direct Import and not through the API, are assigned an import_id in the format: YNAB:[milliunit_amount]:[iso_date]:[occurrence]. For example, a transaction dated 2015-12-30 in the amount of -$294.23 USD would have an import_id of YNAB:-294230:2015- 12-30:1. If a second transaction on the same account was imported and had the same date and same amount, its import_id would be YNAB:-294230:2015-12- 30:2. Using a consistent format will prevent duplicates through Direct Import and File Based Import. If import_id is specified as null, the transaction will be treated as a user entered transaction.
--set-memo <TEXT>
If specified, set the memo of the transaction
--set-payee-id <UUID>
If specified, set the the payee for the transaction
--set-payee-name <TEXT>
If specified, set the payee name. This will be used to resolve the payee by either (1) a matching payee rename rule (only if --set-import-id is also specified) or (2) a payee with the same name or (3) creation of a new payee.

(global arguments omitted; see Global arguments).

ynab get account

Returns a single account

Usage

ynab get account --id <UUID>

Options

--id <UUID>
The ID of the account

(global arguments omitted; see Global arguments).

ynab get budget

Returns a single budget with all related entities

This is effectively a full budget export, and may output a huge amount of data. Only JSON output is supported.

Usage

ynab get budget [OPTIONS]

Options

--last-knowledge-of-server <INTEGER>
The starting server knowledge. If provided, only entities that have changed since last_knowledge_of_server will be included.

(global arguments omitted; see Global arguments).

ynab get budget-settings

Returns settings for a budget

Usage

ynab get budget-settings

Options

(global arguments omitted; see Global arguments).

ynab get category

Returns a single category

By default, amounts (budgeted, activity, balance, etc.) are specific to the current budget month (UTC).

Usage

ynab get category --id <UUID> --month <MONTH>

Options

--id <UUID>
The ID of the category
--month <MONTH>
If specified, returns a single category for a specific budget month. Amounts (budgeted, activity, balance, etc.) are specific to the specified month. [format: Mon-YYYY (e.g. Nov-2018), YYYY-MM (e.g. 2018-11), or current (the current month)] [default: current]

(global arguments omitted; see Global arguments).

ynab get month

Returns a single budget month

Usage

ynab get month [OPTIONS] --month <MONTH>

Options

--include-categories <BOOL>
Include categories in output? [default: true] [possible values: true, false]
--month <MONTH>
The budget month. [format: Mon-YYYY (e.g. Nov-2018), YYYY-MM (e.g. 2018-11), or current (the current month)] [default: current]

(global arguments omitted; see Global arguments).

ynab get payee

Returns single payee

Usage

ynab get payee --id <UUID>

Options

--id <UUID>
The ID of the payee

(global arguments omitted; see Global arguments).

ynab get payee-location

Returns a single payee location

Usage

ynab get payee-location --id <UUID>

Options

--id <UUID>
ID of payee location

(global arguments omitted; see Global arguments).

ynab get scheduled-transaction

Returns a single scheduled transaction

Usage

ynab get scheduled-transaction [OPTIONS] --id <UUID>

Options

--id <UUID>
The ID of the scheduled transaction
--include-subtransactions <BOOL>
Include subtransaction in output? [default: true] [possible values: true, false]

(global arguments omitted; see Global arguments).

ynab get transaction

Returns a single transaction

Usage

ynab get transaction [OPTIONS] --id <UUID>

Options

--id <UUID>
The ID of the transaction
--include-subtransactions <BOOL>
Include subtransaction in output? [default: true] [possible values: true, false]

(global arguments omitted; see Global arguments).

ynab get user

Returns authenticated user information

Usage

ynab get user

Options

(global arguments omitted; see Global arguments).

ynab list accounts

List accounts

Usage

ynab list accounts [OPTIONS]

Options

--columns <COLUMN>...
Columns to include in table/CSV output [default: id,name,type,on-budget,balance,cleared- balance,uncleared-balance,closed] [possible values: all, id, name, type, on-budget, closed, note, balance, cleared-balance, uncleared-balance, transfer-payee-id, deleted]

(global arguments omitted; see Global arguments).

ynab list budgets

List budgets

Usage

ynab list budgets [OPTIONS]

Options

--columns <COLUMN>...
Columns to include in table/CSV output [default: id,name,last-modified,currency-iso- code] [possible values: all, id, name, last- modified, date-format, currency-iso-code, currency-example-format, currency- decimal-digits, currency-decimal-separator, currency-symbol-first, currency- group-separator, currency-symbol, currency-display-symbol]

(global arguments omitted; see Global arguments).

ynab list categories

List categories

Usage

ynab list categories [OPTIONS]

Options

--columns <COLUMN>...
Columns to include in table/CSV output [default: group- name,id,name,budgeted,activity,balance,hidden] [possible values: all, group-id, group-name, group-hidden, group-deleted, id, name, hidden, original-category-group-id, note, budgeted, activity, balance, goal-type, goal-creation-month, goal-target, goal- target-month, goal-percentage-complete, deleted]
--month <MONTH>
List categories for the given month. [format: Mon-YYYY (e.g. Nov-2018), YYYY-MM (e.g. 2018-11), or current (the current month)]

(global arguments omitted; see Global arguments).

ynab list months

List budget months

Each budget contains one or more months, which is where To be Budgeted, Age of Money and category (budgeted / activity / balances) amounts are available.

Usage

ynab list months [OPTIONS]

Options

--columns <COLUMN>...
Columns to include in table/CSV output [default: month,note,income,budgeted,activity,to- be-budgeted,age-of-money] [possible values: all, month, note, income, budgeted, activity, to-be-budgeted, age-of-money]

(global arguments omitted; see Global arguments).

ynab list payee-locations

List payee locations

When you enter a transaction and specify a payee on the YNAB mobile apps, the GPS coordinates for that location are stored, with your permission, so that the next time you are in the same place (like the Grocery store) we can pre-populate nearby payees for you! It's handy and saves you time. This resource makes these locations available. Locations will not be available for all payees.

Usage

ynab list payee-locations [OPTIONS]

Options

--columns <COLUMN>...
Columns to include in table/CSV output [default: id,payee-id,latitude,longitude] [possible values: all, id, payee-id, latitude, longitude, deleted]
--payee-id <UUID>
If specified, list locations for the given payee ID

(global arguments omitted; see Global arguments).

ynab list payees

List payees

Usage

ynab list payees [OPTIONS]

Options

--columns <COLUMN>...
Columns to include in table/CSV output [default: id,name,transfer-account-id] [possible values: all, id, name, transfer-account-id, deleted]

(global arguments omitted; see Global arguments).

ynab list scheduled-transactions

List scheduled transactions

Usage

ynab list scheduled-transactions [OPTIONS]

Options

--columns <COLUMN>...
Columns to include in table/CSV output [default: id,account-name,date- next,frequency,payee-name,category_name,memo,amount] [possible values: all, id, date-first, date-next, frequency, amount, memo, flag-color, account-id, payee-id, category-id, transfer-account-id, deleted, type, parent-transaction-id, account-name, payee-name, category_name]
--include-subtransactions <BOOL>
Include subtransaction in output? [default: true] [possible values: true, false]

(global arguments omitted; see Global arguments).

ynab list transactions

List transactions

Usage

ynab list transactions [OPTIONS]

Options

--account-id <UUID>
If specified, list transactions in the specified account will be included
--category-id <UUID>
If specified, list transactions for the specified category will be included
--columns <COLUMN>...
Columns to include in table/CSV output [default: id,account-name,approved,date,payee- name,category-name,memo,amount,cleared] [possible values: all, id, date, amount, memo, cleared, approved, flag-color, account-id, payee- id, category-id, transfer-account-id, transfer-transaction-id, import-id, deleted, type, parent-transaction-id, account-name, payee-name, category-name]
--include-subtransactions <BOOL>
Include subtransaction in output? [default: true] [possible values: true, false]
--last-knowledge-of-server <INTEGER>
The starting server knowledge. If provided, only entities that have changed since last_knowledge_of_server will be included.
--payee-id <UUID>
If specified, list transactions for the specified payee will be included
--since <DATE>
If specified, only transactions on or after this date will be included. [format: match your budget settings' date format, or ISO 8601 (YYYY-MM-DD) format]
--type <TYPE>
If specified, only transactions of the specified type will be included [default: all] [possible values: all, uncategorized, unapproved]

(global arguments omitted; see Global arguments).

ynab update category

Update an existing month category

Usage

ynab update category [OPTIONS] --id <UUID> --month <MONTH> --set-budgeted <CURRENCY-AMOUNT>

Options

-f, --file <PATH>
If specified, JSON-formatted input containing data to write. The data must match the YNAB API specification (see https://api.youneedabudget.com/v1). Specify - to read from standard input instead of a file.
--id <UUID>
The id of the category
--month <MONTH>
The budget month. [format: Mon-YYYY (e.g. Nov-2018), YYYY-MM (e.g. 2018-11), or current (the current month)] [default: current]
--set-budgeted <CURRENCY-AMOUNT>
Budgeted amount. [format: match your budget settings' number format (the currency symbol and group separators may be omitted)]

(global arguments omitted; see Global arguments).

ynab update transaction

Update an existing transaction

Usage

ynab update transaction [OPTIONS] --id <UUID>

Options

-f, --file <PATH>
If specified, JSON-formatted input containing data to write. The data must match the YNAB API specification (see https://api.youneedabudget.com/v1). Specify - to read from standard input instead of a file.
--id <UUID>
The id of the transaction
--set-account-id <UUID>
Set the account ID
--set-amount <CURRENCY-AMOUNT>
If specified, set the transaction amount. [format: match your budget settings' number format (the currency symbol and group separators may be omitted)]
--set-approved <BOOL>
If specified, set whether or not the transaction is approved. If not supplied, transaction will be unapproved by default. [possible values: true, false]
--set-category-id <UUID>
If specified, set the category for the transaction. Split and Credit Card Payment categories are not permitted and will be ignored if supplied. If an existing transaction has a Split category it cannot be changed.
--set-cleared <STATUS>
If specified, set the cleared status of the transaction [possible values: cleared, uncleared, reconciled]
--set-date <DATE>
If specified, set the transaction date. [format: match your budget settings' date format, or ISO 8601 (YYYY-MM-DD) format]
--set-flag-color <COLOR>
If specified, set the transaction flag [possible values: none, red, orange, yellow, green, blue, purple]
--set-import-id <UUID>
If specified, set the import ID. If specified for a new transaction, the transaction will be treated as Imported and assigned this import_id. If another transaction on the same account with this same import_id is later attempted to be created, it will be skipped to prevent duplication. Transactions imported through File Based Import or Direct Import and not through the API, are assigned an import_id in the format: YNAB:[milliunit_amount]:[iso_date]:[occurrence]. For example, a transaction dated 2015-12-30 in the amount of -$294.23 USD would have an import_id of YNAB:-294230:2015- 12-30:1. If a second transaction on the same account was imported and had the same date and same amount, its import_id would be YNAB:-294230:2015-12- 30:2. Using a consistent format will prevent duplicates through Direct Import and File Based Import. If import_id is specified as null, the transaction will be treated as a user entered transaction.
--set-memo <TEXT>
If specified, set the memo of the transaction
--set-payee-id <UUID>
If specified, set the the payee for the transaction
--set-payee-name <TEXT>
If specified, set the payee name. This will be used to resolve the payee by either (1) a matching payee rename rule (only if --set-import-id is also specified) or (2) a payee with the same name or (3) creation of a new payee.

(global arguments omitted; see Global arguments).

Configuration

Configuration values can be passed into the CLI in three ways (in order of priority):

Command-line arguments

See Global arguments.

Environment variables

The global options each have a corresponding environment variable, shown in the Global arguments description like [env: YNAB_*=]. E.g.

--output <FORMAT>
    Output format [env: YNAB_OUTPUT=]

means the default output format can be set using the YNAB_OUTPUT environment variable.

Configuration files

The configuration files are in "dotenv" format, meaning they contains lines of YNAB_ENV=value pairs. For example:

YNAB_ACCESS_TOKEN=4cfb0a3a5f302f2094747e3eeb0690b9112f39f87548f792b0830001232ac1f6
YNAB_BUDGET_ID=a3a5f302-f209-4747-e3ee-b0690b9112f3

These correspond exactly to the environment variables that can be set.

The CLI looks for configuration files in these locations, in order of priority:

.ynab.env in the current directory
ynab.env in the current directory
.ynab.env in your home directory (varies by OS; see table below)
ynab.env in your (roaming) configuration directory (varies by OS, see table below)

Platform	Value	Example
Linux	`$HOME/.ynab.env`	`/home/alice/.ynab.env`
	`$XDG_CONFIG_HOME/ynab.env` or `$HOME/.config/ynab.env`	`/home/alice/.config/ynab.env`
macOS	`$HOME/.ynab.env`	`/Users/Alice/.ynab.env`
	`$HOME/Library/Preferences/ynab.env`	`/Users/Alice/Library/Preferences/ynab.env`
Windows	`{FOLDERID_Profile}\.ynab.env`	`C:\Users\Alice\.ynab.env`
	`{FOLDERID_RoamingAppData}\ynab.env`	`C:\Users\Alice\AppData\Roaming\ynab.env`

Shell completions

One can generate a completion script for ynab that is compatible with a given shell. The script is output on stdout allowing one to re-direct the output to the file of their choosing. Where you place the file will depend on which shell, and which operating system you are using. Your particular configuration may also determine where these scripts need to be placed.

Here are some common set ups for the three supported shells under Unix and similar operating systems (such as GNU/Linux).

BASH:

Completion files are commonly stored in /etc/bash_completion.d/. Run the command:

$ ynab completions bash > /etc/bash_completion.d/ynab.bash-completion

This installs the completion script. You may have to log out and log back in to your shell session for the changes to take affect.

BASH (macOS/Homebrew):

Homebrew stores bash completion files within the Homebrew directory. With the bash-completion brew formula installed, run the command:

$ ynab completions bash > $(brew --prefix)/etc/bash_completion.d/ynab.bash-completion

FISH:

Fish completion files are commonly stored in $HOME/.config/fish/completions. Run the command:

$ ynab completions fish > ~/.config/fish/completions/ynab.fish

This installs the completion script. You may have to log out and log back in to your shell session for the changes to take affect.

ZSH:

ZSH completions are commonly stored in any directory listed in your $fpath variable. To use these completions, you must either add the generated script to one of those directories, or add your own to this list.

Adding a custom directory is often the safest bet if you are unsure of which directory to use. First create the directory; for this example we'll create a hidden directory inside our $HOME directory:

$ mkdir ~/.zfunc

Then add the following lines to your .zshrc just before compinit:

fpath+=~/.zfunc

Now you can install the completions script using the following command:

$ ynab completions zsh > ~/.zfunc/_ynab

You must then either log out and log back in, or simply run

$ exec zsh

for the new completions to take affect.

CUSTOM LOCATIONS:

Alternatively, you could save these files to the place of your choosing, such as a custom directory inside your $HOME. Doing so will require you to add the proper directives, such as sourceing inside your login script. Consult your shells documentation for how to add such directives.

POWERSHELL:

The powershell completion scripts require PowerShell v5.0+ (which comes Windows 10, but can be downloaded separately for windows 7 or 8.1).

First, check if a profile has already been set

PS C:\> Test-Path $profile

If the above command returns False run the following

PS C:\> New-Item -path $profile -type file -force

Now open the file provided by $profile (if you used the New-Item command it will be ${env:USERPROFILE}\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1

Next, we either save the completions file into our profile, or into a separate file and source it inside our profile. To save the completions into our profile simply use

PS C:\> ynab completions powershell >>

${env:USERPROFILE}\Documents\WindowsPowerShell\Microsoft.PowerShell_profile.ps1

Build from source

Install the Rust toolchain by following the Rust installation instructions.
Download the source code and unpack: .zip, .tar.gz, or clone the Git repository.
In the root of the source tree, run cargo install.

cli-for-ynab cli-for-ynab copied to clipboard

Metadata

Command-line interface for YNAB.

Table of contents

Installation

Initial setup

Personal access token

Budget ID

Other setup

Global arguments

Flags

Options

Commands

ynab create transaction

Usage

Options

ynab get account

Usage

Options

ynab get budget

Usage

Options

ynab get budget-settings

Usage

Options

ynab get category

Usage

Options

ynab get month

Usage

Options

ynab get payee

Usage

Options

ynab get payee-location

Usage

Options

ynab get scheduled-transaction

Usage

Options

ynab get transaction

Usage

Options

ynab get user

Usage

Options

ynab list accounts

Usage

Options

ynab list budgets

Usage

Options

ynab list categories

Usage

Options

ynab list months

Usage

Options

ynab list payee-locations

Usage

Options

ynab list payees

Usage

Options

ynab list scheduled-transactions

Usage

Options

ynab list transactions

Usage

Options

ynab update category

Usage

Options

ynab update transaction

Usage

Options

Configuration

Command-line arguments

Environment variables

Configuration files

cli-for-ynab
cli-for-ynab copied to clipboard