Shoeboxed CLI

Get your receipts and mileage out of Shoeboxed at tax time, right from your computer. Type one line, and your receipts come out in a folder, ready for your accountant.

What you can do

• Pull every receipt in one category, like Home Office or Mileage.
• Add up what you spent in any category for the year.
• Save a tax packet: a folder of receipt PDFs, a spreadsheet, and one combined PDF for your accountant.

Install

You need Node 20 or newer. Then install it once from your terminal, the text window where you type commands:

npm i -g @shoeboxed/cli

That gives you two commands that do the same thing, shoeboxed and the shorter sbx.

Connect your Shoeboxed account

You do this once.

1. Sign in to Shoeboxed and open Settings, then My API apps. Create a new app.
2. In that app, set the Redirect URL to http://localhost:4517/callback.
3. Copy the two keys the app gives you, a client ID and a client secret. Save them somewhere safe, like your password manager.
4. In the terminal, run shoeboxed login, and paste the two keys when it asks.
5. Your browser opens. Click approve, and you are done.

The Shoeboxed CLI keeps your login in your computer's built-in password store, called Keychain on a Mac. It never writes your keys to a plain file, and it keeps you signed in so you skip this next time.

Running it inside a script or an AI assistant? Skip the questions. Pass --client-id and --client-secret on the command, or set the SHOEBOXED_CLIENT_ID and SHOEBOXED_CLIENT_SECRET environment variables.

Commands

| Command | What it does | |---|---| | shoeboxed login | Connect to your Shoeboxed account. | | shoeboxed logout | Sign out and erase your saved login. | | shoeboxed whoami | Show which account you signed in to. | | shoeboxed receipts | List your receipts. Narrow them by category, vendor, year, month, or dates. | | shoeboxed categories | Show each category with how many receipts you have and the total. | | shoeboxed export --out <folder> | Save matching receipts to a folder: the PDFs, a summary.csv spreadsheet, and one combined receipts.pdf for your accountant. |

Narrow your receipts

Add any of these to receipts or export:

• --category a category name, like medical or "home office"
• --exclude-category categories to leave out, separated by commas
• --vendor a store or company name
• --year a year, like 2026
• --month a month, like 2026-04
• --from and --to a start and end date, like 2026-01-01
• --account an account, if you have more than one
• --limit how many to bring back

Add --json to any command to get the raw data instead of a table.

Examples

Get every home office receipt from 2026 and save a tax packet:

shoeboxed export --category "home office" --year 2026 --out ./home-office-2026

Pull your business mileage for the year, leaving out medical and charity trips:

shoeboxed receipts --category Mileage --exclude-category Medical,Charity --year 2026

See what you spent by category last year:

shoeboxed categories --year 2026

One tip on category names: put a name with a space in quotes, like --category "home office". Capitals do not matter. And if a short word could mean two categories, like office in both "Home Office" and "Office Supplies", type the full name.

For developers

Run from source and test:

npm install
npm run dev -- receipts --year 2026   # run from source
npm test                              # tests (vitest)
npm run typecheck                     # tsc --noEmit
npm run lint                          # biome
npm run build                         # tsup -> dist/cli.js

Built on Node 20+, TypeScript and ESM, commander for the CLI, native fetch for HTTP, keytar for the OS keychain, conf for config, vitest, biome, and tsup. It wraps the public Shoeboxed API at api.shoeboxed.com/v2 (github.com/Shoeboxed/api).

Login uses the OAuth authorization-code flow with your own API app credentials, so no shared secret ships in this package. The identity server matches the redirect URL exactly and does not support PKCE, so the loopback port stays fixed at 4517.