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:

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.

Table of contents

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
Options

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

(global arguments omitted; see Global arguments).

ynab get account

Returns a single account

Usage
ynab get account --id <UUID>
Options

(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

(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

(global arguments omitted; see Global arguments).

ynab get month

Returns a single budget month

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

(global arguments omitted; see Global arguments).

ynab get payee

Returns single payee

Usage
ynab get payee --id <UUID>
Options

(global arguments omitted; see Global arguments).

ynab get payee-location

Returns a single payee location

Usage
ynab get payee-location --id <UUID>
Options

(global arguments omitted; see Global arguments).

ynab get scheduled-transaction

Returns a single scheduled transaction

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

(global arguments omitted; see Global arguments).

ynab get transaction

Returns a single transaction

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

(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

(global arguments omitted; see Global arguments).

ynab list budgets

List budgets

Usage
ynab list budgets [OPTIONS]
Options

(global arguments omitted; see Global arguments).

ynab list categories

List categories

Usage
ynab list categories [OPTIONS]
Options

(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

(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

(global arguments omitted; see Global arguments).

ynab list payees

List payees

Usage
ynab list payees [OPTIONS]
Options

(global arguments omitted; see Global arguments).

ynab list scheduled-transactions

List scheduled transactions

Usage
ynab list scheduled-transactions [OPTIONS]
Options

(global arguments omitted; see Global arguments).

ynab list transactions

List transactions

Usage
ynab list transactions [OPTIONS]
Options

(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

(global arguments omitted; see Global arguments).

ynab update transaction

Update an existing transaction

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

(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:

  1. .ynab.env in the current directory
  2. ynab.env in the current directory
  3. .ynab.env in your home directory (varies by OS; see table below)
  4. 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

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