loxo-cli 0.1.0__tar.gz

loxo_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,21 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --all-extras --dev
+      - run: uv run ruff check src tests
+      - run: uv run black --check src tests
+      - run: uv run mypy
+      - run: uv run pytest -q

loxo_cli-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,17 @@
+name: Publish
+on:
+  push:
+    tags: ["v*"]
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write   # trusted publishing (OIDC)
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

loxo_cli-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+docs/

loxo_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## [Unreleased]
+
+### Added
+
+- Initial release of `loxo-cli`.
+- Credential profiles via `loxo configure` (flags > env > `~/.config/loxo/config.toml`),
+  including `api_key_cmd` for pulling the key from a secrets manager.
+- Typed command groups: `people`, `jobs`, `companies`, `deals`, `candidates`,
+  `activities`, `webhooks`, and `ref` (reference data and custom fields).
+- Generic `loxo api METHOD PATH` escape hatch for any endpoint, with `--all`
+  auto-pagination.
+- Scheme-aware pagination (`scroll_id`, `page`, `after_id`) with `--all`.
+- TTY tables plus `--json`/`--jq` for scripting; tolerant models that preserve
+  custom/dynamic fields.
+- Documented exit codes (auth, not-found, rate-limited, server, timeout/network).

loxo_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Andrew Mitchell
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

loxo_cli-0.1.0/PKG-INFO

@@ -0,0 +1,135 @@
+Metadata-Version: 2.4
+Name: loxo-cli
+Version: 0.1.0
+Summary: Unofficial command-line interface for the Loxo recruiting ATS/CRM API
+Project-URL: Homepage, https://github.com/alphaomegateam/loxo-cli
+License: MIT
+License-File: LICENSE
+Requires-Python: >=3.11
+Requires-Dist: click>=8
+Requires-Dist: httpx>=0.27
+Requires-Dist: pydantic>=2
+Requires-Dist: rich>=13
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+# loxo-cli
+
+A fast, ergonomic command-line interface for the [Loxo](https://loxo.co) 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
+
+```bash
+uvx loxo-cli          # run without installing
+pipx install loxo-cli # or install as a user tool
+```
+
+## Quickstart
+
+```bash
+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:
+
+| Variable | Meaning |
+|---|---|
+| `LOXO_API_KEY` | API bearer token |
+| `LOXO_API_SLUG` | Agency slug (the `{slug}` in every request URL) |
+| `LOXO_BASE_URL` | API base URL (default `https://app.loxo.co/api`) |
+| `LOXO_PROFILE` | Default profile name to use |
+
+The config file lives at `~/.config/loxo/config.toml` (or `$XDG_CONFIG_HOME/loxo/config.toml`)
+and is written with `0600` permissions. Example:
+
+```toml
+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. The key is never printed by `loxo configure list`, logged, or shown in
+`--verbose` output.
+
+## Commands
+
+| Group | What it does |
+|---|---|
+| `people` | List/search, get, create, update people |
+| `jobs` | List, get, create, update jobs |
+| `companies` | List/search, get, create, update companies |
+| `deals` | List, get, create, update deals |
+| `candidates` | List/get/add/update candidates under a job |
+| `activities` | List and add person events (activities) |
+| `webhooks` | Full CRUD for webhooks (with enum validation) |
+| `ref` | Reference lookups: job/activity/source/person types, lists, custom fields, hierarchies |
+| `api` | Generic escape hatch — call any endpoint directly |
+| `configure` | Create and list credential profiles |
+
+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`.
+
+## 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 '.[].id'`) without needing the `jq` binary.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Generic error |
+| 2 | Usage error (bad flags/arguments) |
+| 3 | Authentication/authorization failure (401/403) |
+| 4 | Not found (404) |
+| 5 | Rate limited (429) |
+| 6 | Server error (5xx) |
+| 7 | Timeout or network failure |
+
+## 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
+
+```bash
+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](https://www.conventionalcommits.org/).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

loxo_cli-0.1.0/README.md

@@ -0,0 +1,120 @@
+# loxo-cli
+
+A fast, ergonomic command-line interface for the [Loxo](https://loxo.co) 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
+
+```bash
+uvx loxo-cli          # run without installing
+pipx install loxo-cli # or install as a user tool
+```
+
+## Quickstart
+
+```bash
+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:
+
+| Variable | Meaning |
+|---|---|
+| `LOXO_API_KEY` | API bearer token |
+| `LOXO_API_SLUG` | Agency slug (the `{slug}` in every request URL) |
+| `LOXO_BASE_URL` | API base URL (default `https://app.loxo.co/api`) |
+| `LOXO_PROFILE` | Default profile name to use |
+
+The config file lives at `~/.config/loxo/config.toml` (or `$XDG_CONFIG_HOME/loxo/config.toml`)
+and is written with `0600` permissions. Example:
+
+```toml
+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. The key is never printed by `loxo configure list`, logged, or shown in
+`--verbose` output.
+
+## Commands
+
+| Group | What it does |
+|---|---|
+| `people` | List/search, get, create, update people |
+| `jobs` | List, get, create, update jobs |
+| `companies` | List/search, get, create, update companies |
+| `deals` | List, get, create, update deals |
+| `candidates` | List/get/add/update candidates under a job |
+| `activities` | List and add person events (activities) |
+| `webhooks` | Full CRUD for webhooks (with enum validation) |
+| `ref` | Reference lookups: job/activity/source/person types, lists, custom fields, hierarchies |
+| `api` | Generic escape hatch — call any endpoint directly |
+| `configure` | Create and list credential profiles |
+
+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`.
+
+## 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 '.[].id'`) without needing the `jq` binary.
+
+## Exit codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Success |
+| 1 | Generic error |
+| 2 | Usage error (bad flags/arguments) |
+| 3 | Authentication/authorization failure (401/403) |
+| 4 | Not found (404) |
+| 5 | Rate limited (429) |
+| 6 | Server error (5xx) |
+| 7 | Timeout or network failure |
+
+## 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
+
+```bash
+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](https://www.conventionalcommits.org/).
+
+## License
+
+MIT. See [LICENSE](LICENSE).

loxo_cli-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "loxo-cli"
+version = "0.1.0"
+description = "Unofficial command-line interface for the Loxo recruiting ATS/CRM API"
+readme = "README.md"
+license = { text = "MIT" }
+requires-python = ">=3.11"
+dependencies = [
+    "typer>=0.12",
+    "click>=8",  # imported directly in errors.py (ClickException base); declare it explicitly
+    "httpx>=0.27",
+    "pydantic>=2",
+    "rich>=13",
+]
+
+[project.scripts]
+loxo = "loxo_cli.__main__:app"
+
+[project.urls]
+Homepage = "https://github.com/alphaomegateam/loxo-cli"
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-mock>=3.14",
+    "respx>=0.21",
+    "ruff>=0.6",
+    "black>=24",
+    "mypy>=1.11",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/loxo_cli"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+addopts = "-ra"
+
+[tool.ruff]
+line-length = 100
+src = ["src", "tests"]
+
+[tool.black]
+line-length = 100
+target-version = ["py311"]
+
+[tool.mypy]
+python_version = "3.11"
+mypy_path = "src"
+packages = ["loxo_cli"]
+explicit_package_bases = true
+ignore_missing_imports = true

loxo_cli-0.1.0/src/loxo_cli/__init__.py

@@ -0,0 +1 @@
+__version__ = "0.1.0"

loxo_cli-0.1.0/src/loxo_cli/__main__.py

@@ -0,0 +1,132 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any, Optional
+
+import typer
+from rich.console import Console
+
+from loxo_cli import __version__
+from loxo_cli.client import LoxoClient, build_client
+from loxo_cli.commands._app import LoxoGroup
+from loxo_cli.config import LoxoSettings, load_settings
+from loxo_cli.output import render
+
+HELP_EPILOG = "Unofficial — not affiliated with Loxo, Inc."
+
+app = typer.Typer(
+    cls=LoxoGroup,
+    help="loxo — command-line interface for the Loxo recruiting API.",
+    epilog=HELP_EPILOG,
+    no_args_is_help=True,
+)
+
+
+@dataclass
+class AppState:
+    profile: Optional[str]
+    api_key: Optional[str]
+    slug: Optional[str]
+    base_url: Optional[str]
+    json_out: bool
+    jq: Optional[str]
+    verbose: bool
+    no_color: bool
+    config_path: Optional[Path] = None
+    _settings: Optional[LoxoSettings] = field(default=None, repr=False)
+
+    def settings(self) -> LoxoSettings:
+        if self._settings is None:
+            self._settings = load_settings(
+                profile=self.profile,
+                api_key=self.api_key,
+                slug=self.slug,
+                base_url=self.base_url,
+                config_path=self.config_path,
+            )
+        return self._settings
+
+    def client(self) -> LoxoClient:
+        return build_client(self.settings(), verbose=self.verbose)
+
+    def console(self) -> Console:
+        return Console(no_color=self.no_color)
+
+    def emit(self, data: Any, *, columns: list[str] | None = None) -> None:
+        render(
+            data,
+            as_json=self.json_out,
+            jq=self.jq,
+            columns=columns,
+            console=self.console(),
+        )
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    version: bool = typer.Option(
+        False, "--version", callback=_version_callback, is_eager=True, help="Show version and exit."
+    ),
+    profile: Optional[str] = typer.Option(None, "--profile", help="Config profile."),
+    api_key: Optional[str] = typer.Option(None, "--api-key", help="Loxo API key."),
+    slug: Optional[str] = typer.Option(None, "--slug", help="Agency slug."),
+    base_url: Optional[str] = typer.Option(None, "--base-url", help="API base URL."),
+    json_out: bool = typer.Option(False, "--json", help="Force JSON output."),
+    jq: Optional[str] = typer.Option(None, "--jq", help="Filter output (dotted path)."),
+    quiet: bool = typer.Option(False, "--quiet", help="Suppress non-error output."),
+    verbose: bool = typer.Option(False, "-v", "--verbose", help="Log requests to stderr."),
+    no_color: bool = typer.Option(False, "--no-color", help="Disable color."),
+) -> None:
+    """loxo CLI. Unofficial — not affiliated with Loxo, Inc."""
+    ctx.obj = AppState(
+        profile=profile,
+        api_key=api_key,
+        slug=slug,
+        base_url=base_url,
+        json_out=json_out,
+        jq=jq,
+        verbose=verbose,
+        no_color=no_color,
+    )
+
+
+from loxo_cli.commands import api as _api_cmd  # noqa: E402
+from loxo_cli.commands.activities import activities_app  # noqa: E402
+from loxo_cli.commands.candidates import candidates_app  # noqa: E402
+from loxo_cli.commands.companies import companies_app  # noqa: E402
+from loxo_cli.commands.configure import configure_app  # noqa: E402
+from loxo_cli.commands.deals import deals_app  # noqa: E402
+from loxo_cli.commands.jobs import jobs_app  # noqa: E402
+from loxo_cli.commands.people import people_app  # noqa: E402
+from loxo_cli.commands.ref import ref_app  # noqa: E402
+from loxo_cli.commands.webhooks import webhooks_app  # noqa: E402
+
+_api_cmd.register(app)
+app.add_typer(configure_app, name="configure")
+app.add_typer(people_app, name="people")
+app.add_typer(jobs_app, name="jobs")
+app.add_typer(companies_app, name="companies")
+app.add_typer(deals_app, name="deals")
+app.add_typer(candidates_app, name="candidates")
+app.add_typer(activities_app, name="activities")
+app.add_typer(webhooks_app, name="webhooks")
+app.add_typer(ref_app, name="ref")
+
+
+def run() -> None:
+    # Exit-code mapping happens in LoxoGroup.invoke (commands/_app.py, set via
+    # typer.Typer(cls=LoxoGroup)): Typer does NOT honor a raised ClickException's
+    # exit_code, so domain errors become typer.Exit with the mapped code.
+    app()
+
+
+if __name__ == "__main__":
+    run()

loxo_cli-0.1.0/src/loxo_cli/client.py

@@ -0,0 +1,88 @@
+from __future__ import annotations
+
+import sys
+from typing import Any, Mapping
+
+import httpx
+
+from loxo_cli.config import LoxoSettings
+from loxo_cli.errors import LoxoError
+
+TIMEOUT = 30.0
+
+
+def url_for(settings: LoxoSettings, endpoint: str) -> str:
+    return f"{settings.base_url}/{settings.slug}/{endpoint.lstrip('/')}"
+
+
+class LoxoClient:
+    def __init__(self, settings: LoxoSettings, *, verbose: bool = False) -> None:
+        self._settings = settings
+        self._verbose = verbose
+        self._http = httpx.Client(
+            headers={
+                "Authorization": f"Bearer {settings.api_key}",
+                "Accept": "application/json",
+            },
+            follow_redirects=True,
+            timeout=TIMEOUT,
+        )
+
+    def __enter__(self) -> "LoxoClient":
+        return self
+
+    def __exit__(self, *exc: object) -> None:
+        self.close()
+
+    def close(self) -> None:
+        self._http.close()
+
+    def request(
+        self,
+        method: str,
+        endpoint: str,
+        *,
+        params: Mapping[str, Any] | None = None,
+        json: Any | None = None,
+    ) -> Any:
+        target = url_for(self._settings, endpoint)
+        if self._verbose:
+            # Method + URL only. Never headers (would leak the bearer token).
+            print(f"{method.upper()} {target}", file=sys.stderr)
+        headers = {"Content-Type": "application/json"} if json is not None else None
+        try:
+            response = self._http.request(method, target, params=params, json=json, headers=headers)
+            response.raise_for_status()
+        except httpx.TimeoutException as exc:
+            raise LoxoError(
+                f"Loxo {method} {endpoint} timed out", status_code=None, is_timeout=True
+            ) from exc
+        except httpx.HTTPStatusError as exc:
+            raise LoxoError(
+                f"Loxo {method} {endpoint} returned {exc.response.status_code}: "
+                f"{exc.response.text[:500]}",
+                status_code=exc.response.status_code,
+            ) from exc
+        except httpx.HTTPError as exc:
+            raise LoxoError(
+                f"Loxo {method} {endpoint} request failed: {exc}", status_code=None
+            ) from exc
+        if not response.content:
+            return None
+        return response.json()
+
+    def get(self, endpoint: str, **kw: Any) -> Any:
+        return self.request("GET", endpoint, **kw)
+
+    def post(self, endpoint: str, **kw: Any) -> Any:
+        return self.request("POST", endpoint, **kw)
+
+    def put(self, endpoint: str, **kw: Any) -> Any:
+        return self.request("PUT", endpoint, **kw)
+
+    def delete(self, endpoint: str, **kw: Any) -> Any:
+        return self.request("DELETE", endpoint, **kw)
+
+
+def build_client(settings: LoxoSettings, *, verbose: bool = False) -> LoxoClient:
+    return LoxoClient(settings, verbose=verbose)

loxo_cli-0.1.0/src/loxo_cli/commands/_app.py

@@ -0,0 +1,28 @@
+from __future__ import annotations
+
+from typing import Any
+
+import typer
+from typer.core import TyperGroup
+
+from loxo_cli.errors import ConfigError, LoxoError
+
+
+class LoxoGroup(TyperGroup):
+    """Root command group that maps loxo's domain errors to documented exit codes.
+
+    Typer's invocation path does NOT honor a raised ``ClickException``'s
+    ``exit_code`` (it surfaces as a generic exit 1 with no message). Set this as
+    the root app's group class via the supported ``typer.Typer(cls=LoxoGroup)``
+    hook: its ``invoke`` wraps the entire command tree, so every command — nested
+    sub-app commands and root-level commands alike — gets its ``LoxoError`` /
+    ``ConfigError`` converted into ``typer.Exit`` with the mapped code, with a
+    clean message on stderr. Command files stay plain ``typer.Typer``.
+    """
+
+    def invoke(self, ctx) -> Any:  # ctx is typer's vendored-click Context
+        try:
+            return super().invoke(ctx)
+        except (LoxoError, ConfigError) as exc:
+            typer.echo(f"Error: {exc.format_message()}", err=True)
+            raise typer.Exit(code=exc.exit_code) from exc