hibob-cli

CLI for the HiBob HR platform. Covers all 157 API endpoints with typed flags, pretty output, and custom commands.

Install

make build
make install INSTALL_DIR=~/.local/bin

Requires: Go 1.21+, Python 3.9+

Auth

hibob auth login
# Enter Service User ID and Token
# Credentials saved to ~/.hibob-cli/config.yaml

hibob auth status

Service user credentials are configured in Bob Admin → Settings → API → Service Users.

Usage

# Search employees
hibob people search-for-employees --fields displayName,email,work.department

# Who's out today (time off only)
hibob whosout

# Who's out today (time off + holiday calendars + working patterns)
hibob whosout --include-calendars

# Include custom employee fields
hibob whosout --include-custom-fields

# Time off requests
hibob timeoff read-a-list-of-whos-out-of-the-office-today-or-on --include-private

# Submit time off
hibob timeoff submit-a-new-time-off-request 12345 \
    --policy-type "Paid Time Off" \
    --request-range-type days \
    --start-date 2026-05-01 \
    --end-date 2026-05-05

# Reports
hibob reports read-company-reports
hibob reports download-the-report-by-id 31134627 --format json

# Goals
hibob goals search-goals
hibob goals update-goal-status 42 --status completed

# Any command with raw JSON body
hibob people create-company-employee -b '{"firstName":"John","surname":"Doe"}'

# Pipe from stdin
echo '{"fields":["displayName"]}' | hibob people search-for-employees

Output Formats

# Pretty table (default) — colored, human-readable
hibob people search-for-employees

# JSON — for piping to jq or scripts
hibob people search-for-employees -o json

Holiday Calendars

Bob's public API doesn't expose holiday calendar dates. To enable holiday detection in whosout:

# 1. Get browser cookie from app.hibob.com (DevTools → Network → Cookie header)
# 2. Sync calendars (one-time, data changes rarely)
hibob calendars sync --cookie "hibob=eyJ...; oauth-token=FMx..."

# 3. Now whosout includes holidays
hibob whosout --include-calendars

Calendars are saved to ~/.hibob-cli/calendars.json.

Agent Integration

# Generate machine-readable schema for LLM agents
hibob agent-schema
# → /tmp/hibob-agent-schema.json (157 commands with flags, args, types)

Agents read the schema file, then invoke commands via bash. No MCP required.

Reproducible Build

# Full pipeline: sync API docs → extract OpenAPI → codegen → build → schema
make generate

# Individual steps
make sync_hibob_api_reference   # Download .md from apidocs.hibob.com
make extract_openapi            # Merge into api/openapi.json
make generate_client            # oapi-codegen → Go types
make generate_commands           # Python → Cobra commands with typed flags
make build                      # go build
make agent_schema               # Generate agent schema

Project Structure

cmd/hibob/main.go                    # Entry point
internal/
├── api/                             # Generated types + client (36K lines)
├── client/
│   ├── client.go                    # HTTP client with Basic Auth
│   └── fields.go                    # Custom fields metadata helper
├── config/config.go                 # Viper config (~/.hibob-cli/)
├── output/output.go                 # Pretty/JSON formatter
└── commands/
    ├── root.go                      # Root command + output wiring
    ├── auth.go                      # auth login/status
    ├── calendars.go                 # calendars sync/show (cookie auth)
    ├── whosout.go                   # Combined who's out
    ├── agent_schema.go              # Agent schema generator
    └── *.gen.go                     # Generated commands (151)
scripts/
├── sync_hibob_api_reference.py      # Download API docs as .md
├── extract_openapi.py               # Merge OpenAPI specs
├── generate_client.sh               # oapi-codegen wrapper
└── generate_commands.py             # Cobra command generator
api/
├── openapi.json                     # Merged OpenAPI spec
└── agent-schema.json                # Agent tool schema
AIDOC/HIBOB/API_REFERENCE/           # 216 downloaded .md files
Makefile