bamboohr-cli

Command-line interface for the BambooHR API. 17 commands across 4 domains — employees, time off, files, and metadata.

Install

npm install -g bamboohr-cli

Setup

Set two environment variables in your shell profile:

export BAMBOO_TOKEN="your-api-token"           # BambooHR > Settings > API Keys
export BAMBOO_COMPANY_DOMAIN="mycompany"        # the subdomain in mycompany.bamboohr.com

Argument conventions

• One positional, and it is the group's subject — the employee id, the file id, the request id.
• Employee-scoped commands default to you when the [employeeId] positional is omitted.
• Sub-entities and filters are entity-qualified flags — --employee-id, --request-id, --type-id. There is no --id.
• Prose is --note, with a --note-file <path|-> companion that reads a file or stdin.

Commands

All commands output JSON. Add --pretty to pretty-print.

employee

| Command | Description | | -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | | bamboohr employee get [employeeId] | One employee's record, defaulting to you. --fields selects fields, --include-future shows scheduled changes, --with-photos adds photo urls | | bamboohr employee search [query] | Employees matching a name fragment and/or --department, --division, --location, --supervisor (me resolves to you) | | bamboohr employee directory | The whole company directory. --with-photos adds photo urls | | bamboohr employee photo <employeeId> | Writes the profile photo to --output, at --size original\|large\|medium\|small\|xs\|tiny | | bamboohr employee goals <employeeId> | Performance goals, filtered by --filter open\|closed\|all |

timeoff

| Command | Description | | -------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | bamboohr timeoff types | Time-off type names and the ids that timeoff create --type-id expects. --requestable narrows to types you can book | | bamboohr timeoff balance [employeeId] | Estimated balances per type, defaulting to you. --date projects the balance to a future date | | bamboohr timeoff requests | Time-off requests, defaulting to yours. --status, --start-date/--end-date, --type-id, --request-id filter; --employee-id reads one other person, --all-employees reads everyone; --action approve returns only what awaits your approval | | bamboohr timeoff create [employeeId] | Books time off between --start-date and --end-date for --type-id. The per-day breakdown is generated for you (0 on weekends and company holidays); --dates <json> overrides it for half days and custom splits | | bamboohr timeoff update-status <requestId> | Sets --status approved\|denied\|canceled, with an optional --note | | bamboohr timeoff whos-out | Who is out, and which company holidays fall in the window set by --start-date/--end-date |

file

| Command | Description | | ---------------------------- | -------------------------------------------- | | bamboohr file list | Company files and the categories they sit in | | bamboohr file get <fileId> | Downloads one company file to --output |

meta

| Command | Description | | --------------------------- | ---------------------------------------------------- | | bamboohr meta fields | Every field name employee get --fields accepts | | bamboohr meta departments | Department names, for employee search --department | | bamboohr meta divisions | Division names, for employee search --division | | bamboohr meta locations | Office locations, for employee search --location |

Pagination

There is none. Every BambooHR endpoint used here returns its full result set in one response, so no command takes --limit or --start; employee search filters the directory client-side.

Examples

# Look up your own employee record
bamboohr employee get

# Find someone by name, or by where they sit
bamboohr employee search "Jane"
bamboohr employee search --department Engineering

# Your direct reports
bamboohr employee search --supervisor me

# Download a photo
bamboohr employee photo 123 --output ./photo.jpg --size large

# Check who's out this week
bamboohr timeoff whos-out --start-date 2026-04-20 --end-date 2026-04-24

# Find the type id, then request a day off
bamboohr timeoff types --requestable
bamboohr timeoff create --start-date 2026-04-20 --end-date 2026-04-20 --type-id 83

# Book a half day
bamboohr timeoff create --start-date 2026-04-20 --end-date 2026-04-20 --type-id 83 --dates '[{"date":"2026-04-20","amount":0.5}]'

# What is waiting on my approval, and act on it
bamboohr timeoff requests --action approve
bamboohr timeoff update-status 4567 --status approved --note "Enjoy"

# Check a balance, now and at year end
bamboohr timeoff balance
bamboohr timeoff balance --date 2026-12-31

# List available fields for custom queries
bamboohr meta fields

Renamed in 2.0.0

The argument surface was unified across the whole CLI suite. There are no deprecation shims:

| Before | Now | | ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------ | | timeoff requests --id <id> | timeoff requests --request-id <id> | | timeoff requests --employee <id> | timeoff requests --employee-id <id> | | timeoff requests --type <id> | timeoff requests --type-id <id> | | timeoff requests --all | timeoff requests --all-employees — across the suite --all means "every page", and this flag has always meant "every person" | | timeoff create --amount <n> | removed. BambooHR does not spread a total across a date range, so the per-day breakdown is generated instead; use --dates to override it | | employee get\|goals\|photo <id> | employee get\|goals\|photo <employeeId> (the positional is named consistently across the suite) |