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.
Table of contents
- Installation
- Initial 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. Useynab 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 ofYNAB:-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 beYNAB:-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
), orcurrent
(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
), orcurrent
(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
), orcurrent
(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
), orcurrent
(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 ofYNAB:-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 beYNAB:-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 directoryynab.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 source
ing
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
.