loxo-cli

A fast, ergonomic command-line interface for the Loxo recruiting ATS/CRM REST API. It offers typed subcommands for the common resources (people, jobs, companies, deals, candidates, activities, webhooks, reference data) plus a generic loxo api escape hatch that can call any endpoint. Output is human-friendly tables on a terminal and clean JSON when piped, so it fits both interactive use and scripts.

Unofficial — not affiliated with Loxo, Inc.

Install

uvx loxo-cli          # run without installing
pipx install loxo-cli # or install as a user tool

Quickstart

loxo configure                       # set up a profile
loxo people list --query "engineer"  # human table
loxo people list --json | jq '.'     # JSON for scripts
loxo api GET jobs/123                # raw escape hatch

Configuration

Credentials resolve with the precedence flags > environment > config file.

Environment variables:

The config file lives at ~/.config/loxo/config.toml (or $XDG_CONFIG_HOME/loxo/config.toml) and is written with 0600 permissions. Example:

default_profile = "prod"

[profile.prod]
slug = "acme"
base_url = "https://app.loxo.co/api"
api_key = "your-token"

[profile.staging]
slug = "acme-staging"
# Pull the key from a secrets manager instead of storing it in plaintext:
api_key_cmd = "op read op://Private/loxo-staging/credential"

api_key_cmd is run on demand and its stdout is used as the key, so the secret never has to live in the file. Set it without hand-editing the file via loxo configure --api-key-cmd "op read op://Private/loxo/credential". The key is never printed by loxo configure list, logged, or shown in --verbose output.

Commands

Custom (dynamic) fields are supported on writes via repeatable --field key=value (use key[]=value to force a list, e.g. hierarchy fields). Discover valid keys with loxo ref custom-fields, which maps each key (custom_text_3) to its plain-language name and type. Filter to one object with --object deal (matches the field's item_type, case-insensitive) and hide built-ins with --custom-only. For a hierarchy field, loxo ref hierarchies custom_hierarchy_4 --object deal lists its options (name + id); the FIELD argument also accepts the numeric field id.

Output

On a terminal, list and object results render as Rich tables. Pipe the command or pass --json to get machine-readable JSON; --jq '<path>' applies a small built-in selector (e.g. --jq '.results', --jq '.[].id', --jq '.results.0.title' — the leading . is optional) without needing the jq binary.

--json output is always plain (never ANSI-colored) so it can be piped straight into jq, json.loads, etc. Table color is disabled automatically when stdout is not a terminal, and can be turned off explicitly with --no-color or the NO_COLOR environment variable.

Filtering vs. search

--query/-q (and api ... -p query=) is a ranked full-text search, not an exact filter: the API returns a broad, relevance-ordered set (e.g. -q "VP of Digital" also matches unrelated VP * roles further down). To narrow a result set to exact matches, add --filter field=value (repeatable) on list commands — it post-filters the returned records client-side. Object-valued fields match on their name, so --filter status=Active matches a status of {"id": 70251, "name": "Active"}. Example:

loxo jobs list -q "VP of Digital" --filter status=Active

Exit codes

Pagination

Loxo paginates differently per endpoint: cursor (scroll_id), offset (page), and keyset (after_id). loxo-cli detects and handles all three. List commands fetch a single page by default; pass --all to transparently walk every page. The generic loxo api ... --all auto-detects the scheme (or force it with --paginate scroll_id|page|after_id).

Contributing

uv sync                 # install dependencies
uv run pytest           # run the test suite (HTTP is mocked; no live calls)
uv run ruff check src tests
uv run black --check src tests
uv run mypy

Commits follow Conventional Commits.

License

MIT. See LICENSE.