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 ontop of the API (such features may be added in the future; feel free to suggest one). For now, no data is cached locally.

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

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/ynab-0.1.0-x86_64-*
$ sudo cp /path/to/ynab-0.1.0-x86_64-* /usr/local/bin/ynab

On Windows, rename 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

Budget ID

The default budget ID (last-used) will use your most recently used budget, but it doesn't work reliably in many parts of the API. As such, you should also configure the actual budget ID of your main budget.

The easiest way to to get the budget ID is by logging into YNAB on your browser and opening your budget, and then copy the ID from the URL. E.g. if the URL is https://app.youneedabudget.com/a3a5f302-f209-4747-e3ee-b0690b9112f3/budget, then the budget ID is a3a5f302-f209-4747-e3ee-b0690b9112f3. Alternatively, use ynab list budgets to find the budget ID (the first column).

Now add the YNAB_BUDGET_ID=<ID> to .ynab.env. For example, a file with both values:

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

Other setup

See Configuration for more configuration options.

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-transactio