hiringcafe-cli 0.1.4__tar.gz

hiringcafe_cli-0.1.4/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 chen-gdp
+
+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.

hiringcafe_cli-0.1.4/PKG-INFO

@@ -0,0 +1,145 @@
+Metadata-Version: 2.4
+Name: hiringcafe-cli
+Version: 0.1.4
+Summary: Spec-driven Python CLI for Hiring Cafe job search and saved-job tracking
+Author: chen-gdp
+Author-email: chen-gdp <146709874+chen-gdp@users.noreply.github.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/chen-gdp/hiringcafe-cli
+Project-URL: Repository, https://github.com/chen-gdp/hiringcafe-cli
+Project-URL: Issues, https://github.com/chen-gdp/hiringcafe-cli/issues
+Project-URL: Changelog, https://github.com/chen-gdp/hiringcafe-cli/blob/main/CHANGELOG.md
+Description-Content-Type: text/markdown
+
+# HiringCafe CLI
+
+Give your AI agent Hiring Cafe superpowers: search jobs, inspect postings, and keep your Hiring Cafe saved-job board in sync without a browser.
+
+```bash
+hiringcafe search "python developer" --pages 3 --jsonl
+```
+
+The result is stable JSON/JSONL, explicit exit codes, cached anonymous reads, bounded retries, and authenticated actions against your real Hiring Cafe account.
+
+> **Unofficial client.** This project is not affiliated with, endorsed by, or supported by Hiring Cafe. Use your own account, respect the service, and expect upstream APIs to change.
+
+## For agents
+
+Agents can install and verify the CLI in three commands:
+
+```bash
+uv tool install hiringcafe-cli
+hiringcafe search "python developer" --page 0 --json
+```
+
+For persistent installations, use `uv tool install hiringcafe-cli` or `pipx install hiringcafe-cli`.
+
+Feed the output directly to your tooling:
+
+```bash
+# One JSON object per page
+hiringcafe search "python developer" --pages 3 --jsonl
+
+# One line per job
+hiringcafe search "python developer" --pages 3 --json | jq -c '.jobs[]'
+
+# Machine-readable result count
+hiringcafe count "python developer" --json
+```
+
+Import an existing Firebase refresh token without an interactive password prompt:
+
+```bash
+printf '%s\n' "$HIRINGCAFE_REFRESH_TOKEN" | hiringcafe auth import
+hiringcafe saved-jobs list --json
+```
+
+Safe automation contract:
+
+- JSON success output goes to stdout; cache diagnostics go to stderr.
+- Stable exit codes describe transport, input, rate-limit, auth, and conflict outcomes.
+- Passwords and Firebase ID tokens are never written to disk.
+- Authenticated mutations are never retried or cached.
+- Anonymous search/count responses use a 15-minute cache; job details use 24 hours.
+
+## For humans
+
+```bash
+hiringcafe auth login --email you@example.com
+hiringcafe search "python developer" --page 0 --json
+hiringcafe job show <objectID> --json
+hiringcafe saved-jobs list --json
+hiringcafe auth logout
+```
+
+The password is read through hidden input, exchanged once, and discarded.
+
+## Saved jobs
+
+These commands modify your real Hiring Cafe account. Review object IDs and confirmation prompts before changing data.
+
+```bash
+hiringcafe saved-jobs save <objectID> --stage saved
+hiringcafe saved-jobs stage <objectID> --stage interviewing
+hiringcafe saved-jobs remove <objectID> --yes
+```
+
+Valid stages are `saved`, `applied`, `interviewing`, `offer`, `rejected`, `ghosted`, and `hidden`.
+
+## Local data
+
+| Data | Location | Notes |
+|---|---|---|
+| Refresh token | `~/.config/hiringcafe-cli/session.json` | owner-only file; removed by logout |
+| Anonymous cache | `~/.cache/hiringcafe-cli/cache/v1/` | public search/job data only |
+
+Set `HIRINGCAFE_CONFIG_HOME` or `HIRINGCAFE_CACHE_HOME` to use different roots.
+
+```bash
+hiringcafe search "python developer" --no-cache
+hiringcafe search "python developer" --cache-ttl 3600
+hiringcafe cache purge
+```
+
+## Exit codes
+
+| Code | Agent action |
+|---:|---|
+| `0` | success |
+| `1` | transport, HTTP, parsing, or API error; inspect stderr |
+| `2` | invalid arguments or search state; fix the request |
+| `3` | rate limited; wait and retry |
+| `4` | no stored credential; authenticate first |
+| `5` | stored credential rejected; re-authenticate |
+| `6` | write conflict or prerequisite missing; refresh state |
+
+## Development
+
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync
+uv run pytest
+uv run hiringcafe --help
+uv run pre-commit run --all-files
+```
+
+Normal tests do not access the network. The verified anonymous endpoint probe is opt-in:
+
+```bash
+LIVE=1 uv run hiringcafe probe
+```
+
+Every implementation change traces to `specs/pr-*/spec.md` and the roadmap. Never commit credentials, Firebase tokens, cookies, real UIDs, emails, or private account data.
+
+Beta status: search, job details, authentication, and saved-job workflows are implemented. Browser OAuth login remains intentionally deferred. See [`roadmap.md`](roadmap.md) and [`specs/`](specs/).

hiringcafe_cli-0.1.4/README.md

@@ -0,0 +1,122 @@
+# HiringCafe CLI
+
+Give your AI agent Hiring Cafe superpowers: search jobs, inspect postings, and keep your Hiring Cafe saved-job board in sync without a browser.
+
+```bash
+hiringcafe search "python developer" --pages 3 --jsonl
+```
+
+The result is stable JSON/JSONL, explicit exit codes, cached anonymous reads, bounded retries, and authenticated actions against your real Hiring Cafe account.
+
+> **Unofficial client.** This project is not affiliated with, endorsed by, or supported by Hiring Cafe. Use your own account, respect the service, and expect upstream APIs to change.
+
+## For agents
+
+Agents can install and verify the CLI in three commands:
+
+```bash
+uv tool install hiringcafe-cli
+hiringcafe search "python developer" --page 0 --json
+```
+
+For persistent installations, use `uv tool install hiringcafe-cli` or `pipx install hiringcafe-cli`.
+
+Feed the output directly to your tooling:
+
+```bash
+# One JSON object per page
+hiringcafe search "python developer" --pages 3 --jsonl
+
+# One line per job
+hiringcafe search "python developer" --pages 3 --json | jq -c '.jobs[]'
+
+# Machine-readable result count
+hiringcafe count "python developer" --json
+```
+
+Import an existing Firebase refresh token without an interactive password prompt:
+
+```bash
+printf '%s\n' "$HIRINGCAFE_REFRESH_TOKEN" | hiringcafe auth import
+hiringcafe saved-jobs list --json
+```
+
+Safe automation contract:
+
+- JSON success output goes to stdout; cache diagnostics go to stderr.
+- Stable exit codes describe transport, input, rate-limit, auth, and conflict outcomes.
+- Passwords and Firebase ID tokens are never written to disk.
+- Authenticated mutations are never retried or cached.
+- Anonymous search/count responses use a 15-minute cache; job details use 24 hours.
+
+## For humans
+
+```bash
+hiringcafe auth login --email you@example.com
+hiringcafe search "python developer" --page 0 --json
+hiringcafe job show <objectID> --json
+hiringcafe saved-jobs list --json
+hiringcafe auth logout
+```
+
+The password is read through hidden input, exchanged once, and discarded.
+
+## Saved jobs
+
+These commands modify your real Hiring Cafe account. Review object IDs and confirmation prompts before changing data.
+
+```bash
+hiringcafe saved-jobs save <objectID> --stage saved
+hiringcafe saved-jobs stage <objectID> --stage interviewing
+hiringcafe saved-jobs remove <objectID> --yes
+```
+
+Valid stages are `saved`, `applied`, `interviewing`, `offer`, `rejected`, `ghosted`, and `hidden`.
+
+## Local data
+
+| Data | Location | Notes |
+|---|---|---|
+| Refresh token | `~/.config/hiringcafe-cli/session.json` | owner-only file; removed by logout |
+| Anonymous cache | `~/.cache/hiringcafe-cli/cache/v1/` | public search/job data only |
+
+Set `HIRINGCAFE_CONFIG_HOME` or `HIRINGCAFE_CACHE_HOME` to use different roots.
+
+```bash
+hiringcafe search "python developer" --no-cache
+hiringcafe search "python developer" --cache-ttl 3600
+hiringcafe cache purge
+```
+
+## Exit codes
+
+| Code | Agent action |
+|---:|---|
+| `0` | success |
+| `1` | transport, HTTP, parsing, or API error; inspect stderr |
+| `2` | invalid arguments or search state; fix the request |
+| `3` | rate limited; wait and retry |
+| `4` | no stored credential; authenticate first |
+| `5` | stored credential rejected; re-authenticate |
+| `6` | write conflict or prerequisite missing; refresh state |
+
+## Development
+
+Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/).
+
+```bash
+uv sync
+uv run pytest
+uv run hiringcafe --help
+uv run pre-commit run --all-files
+```
+
+Normal tests do not access the network. The verified anonymous endpoint probe is opt-in:
+
+```bash
+LIVE=1 uv run hiringcafe probe
+```
+
+Every implementation change traces to `specs/pr-*/spec.md` and the roadmap. Never commit credentials, Firebase tokens, cookies, real UIDs, emails, or private account data.
+
+Beta status: search, job details, authentication, and saved-job workflows are implemented. Browser OAuth login remains intentionally deferred. See [`roadmap.md`](roadmap.md) and [`specs/`](specs/).

hiringcafe_cli-0.1.4/pyproject.toml

@@ -0,0 +1,74 @@
+[project]
+name = "hiringcafe-cli"
+version = "0.1.4"
+description = "Spec-driven Python CLI for Hiring Cafe job search and saved-job tracking"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+requires-python = ">=3.11"
+dependencies = []
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+[[project.authors]]
+name = "chen-gdp"
+email = "146709874+chen-gdp@users.noreply.github.com"
+
+[project.urls]
+Homepage = "https://github.com/chen-gdp/hiringcafe-cli"
+Repository = "https://github.com/chen-gdp/hiringcafe-cli"
+Issues = "https://github.com/chen-gdp/hiringcafe-cli/issues"
+Changelog = "https://github.com/chen-gdp/hiringcafe-cli/blob/main/CHANGELOG.md"
+
+[project.scripts]
+hiringcafe = "hiringcafe_cli:main"
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.3.0",
+    "pytest>=9.0.0",
+    "ruff>=0.14.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.11.16,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+exclude = [
+    ".venv",
+    "dist",
+    "__pycache__",
+]
+
+[tool.ruff.lint]
+select = [
+    "E",
+    "F",
+    "I",
+    "B",
+    "UP",
+    "S",
+]
+ignore = [
+    "S310",
+    "S311",
+    "UP017",
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = [
+    "S101",
+    "S105",
+    "S106",
+]

hiringcafe_cli-0.1.4/pyproject.toml.orig

@@ -0,0 +1,62 @@
+[project]
+name = "hiringcafe-cli"
+version = "0.1.4"
+description = "Spec-driven Python CLI for Hiring Cafe job search and saved-job tracking"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+    { name = "chen-gdp", email = "146709874+chen-gdp@users.noreply.github.com" }
+]
+requires-python = ">=3.11"
+dependencies = []
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+]
+
+[project.urls]
+Homepage = "https://github.com/chen-gdp/hiringcafe-cli"
+Repository = "https://github.com/chen-gdp/hiringcafe-cli"
+Issues = "https://github.com/chen-gdp/hiringcafe-cli/issues"
+Changelog = "https://github.com/chen-gdp/hiringcafe-cli/blob/main/CHANGELOG.md"
+
+[dependency-groups]
+dev = [
+    "pre-commit>=4.3.0",
+    "pytest>=9.0.0",
+    "ruff>=0.14.0",
+]
+
+[project.scripts]
+hiringcafe = "hiringcafe_cli:main"
+
+[build-system]
+requires = ["uv_build>=0.11.16,<0.12.0"]
+build-backend = "uv_build"
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+exclude = [".venv", "dist", "__pycache__"]
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B", "UP", "S"]
+ignore = [
+    "S310", # all transport URLs are fixed HTTPS constants or verified site URLs
+    "S311", # random jitter is for retry timing, not cryptography
+    "UP017", # timezone.utc is the Python 3.11-compatible spelling
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = [
+    "S101", # assertions are the project's test contract
+    "S105", # synthetic credential names in isolated tests
+    "S106", # synthetic credential values in isolated tests
+]

hiringcafe_cli-0.1.4/src/hiringcafe_cli/__init__.py

@@ -0,0 +1,152 @@
+"""HiringCafe CLI package interface."""
+
+import argparse
+import sys
+
+from hiringcafe_cli import (
+    auth,
+    count,
+    job,
+    probe,
+    saved_jobs_list,
+    saved_jobs_remove,
+    saved_jobs_save,
+    saved_jobs_stage,
+    search,
+)
+from hiringcafe_cli.cache import CacheStore, active_cache_root
+from hiringcafe_cli.firebase import FirebaseAuthError, FirebaseTransportError
+from hiringcafe_cli.http_client import HireCafeHTTPError, HireCafeTransportError
+from hiringcafe_cli.saved_jobs import VALID_STAGES
+from hiringcafe_cli.saved_jobs_list import FirestoreError
+from hiringcafe_cli.search_state import InvalidSearchState
+
+__version__ = "0.1.0"
+
+EXIT_CONTRACT = """\
+Exit codes:
+  0 success
+  1 transport, HTTP, parsing, or API error
+  2 invalid arguments or search state
+  3 rate limited
+  4 no stored credential
+  5 stored credential rejected
+  6 write conflict or prerequisite missing
+"""
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """Build the root CLI parser.
+
+    Returns:
+        An argparse parser implementing the PR 0.1 bootstrap contract.
+    """
+    parser = argparse.ArgumentParser(
+        prog="hiringcafe",
+        description="Hiring Cafe command-line interface",
+        epilog=EXIT_CONTRACT,
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {__version__}")
+    cache_options = argparse.ArgumentParser(add_help=False)
+    cache_options.add_argument("--no-cache", action="store_true")
+    cache_options.add_argument("--cache-ttl", type=int)
+    subparsers = parser.add_subparsers(dest="command")
+    probe_parser = subparsers.add_parser("probe", help="run the opt-in live endpoint probe")
+    probe_parser.set_defaults(handler=probe.main)
+    search_parser = subparsers.add_parser("search", help="search jobs", parents=[cache_options])
+    search_parser.add_argument("query", nargs="?", default="")
+    search_parser.add_argument("--page", type=int, default=0)
+    search_parser.add_argument("--pages", type=int, default=1)
+    search_parser.add_argument("--raw-search-state")
+    search_parser.add_argument("--json", action="store_true")
+    search_parser.add_argument("--jsonl", action="store_true")
+    search_parser.set_defaults(handler=search.run)
+    count_parser = subparsers.add_parser("count", help="print total result count", parents=[cache_options])
+    count_parser.add_argument("query", nargs="?", default="")
+    count_parser.add_argument("--raw-search-state")
+    count_parser.add_argument("--json", action="store_true")
+    count_parser.set_defaults(handler=count.run)
+    job_parser = subparsers.add_parser("job", help="inspect job details")
+    job_subparsers = job_parser.add_subparsers(dest="job_command", required=True)
+    job_show_parser = job_subparsers.add_parser("show", help="show a job description", parents=[cache_options])
+    job_show_parser.add_argument("object_id")
+    job_show_parser.add_argument("--json", action="store_true")
+    job_show_parser.set_defaults(handler=job.run)
+    auth_parser = subparsers.add_parser("auth", help="manage Firebase authentication")
+    auth_subparsers = auth_parser.add_subparsers(dest="auth_command", required=True)
+    auth_login_parser = auth_subparsers.add_parser("login", help="log in to Firebase")
+    auth_login_parser.add_argument("--email", required=True)
+    auth_login_parser.set_defaults(handler=auth.login_email)
+    auth_import_parser = auth_subparsers.add_parser("import", help="import a refresh token")
+    auth_import_parser.set_defaults(handler=auth.import_token)
+    auth_status_parser = auth_subparsers.add_parser("status", help="show credential status")
+    auth_status_parser.add_argument("--json", action="store_true")
+    auth_status_parser.set_defaults(handler=auth.status)
+    auth_logout_parser = auth_subparsers.add_parser("logout", help="remove the local session")
+    auth_logout_parser.set_defaults(handler=auth.logout)
+    saved_parser = subparsers.add_parser("saved-jobs", help="manage saved jobs")
+    saved_subparsers = saved_parser.add_subparsers(dest="saved_command", required=True)
+    saved_list_parser = saved_subparsers.add_parser("list", help="list saved jobs")
+    saved_list_parser.add_argument("--stage", choices=sorted(VALID_STAGES))
+    saved_list_parser.add_argument("--json", action="store_true")
+    saved_list_parser.set_defaults(handler=saved_jobs_list.run)
+    saved_save_parser = saved_subparsers.add_parser("save", help="save a job")
+    saved_save_parser.add_argument("object_id")
+    saved_save_parser.add_argument("--stage", default="saved")
+    saved_save_parser.set_defaults(handler=saved_jobs_save.run)
+    saved_stage_parser = saved_subparsers.add_parser("stage", help="update a job stage")
+    saved_stage_parser.add_argument("object_id")
+    saved_stage_parser.add_argument("--stage", required=True)
+    saved_stage_parser.set_defaults(handler=saved_jobs_stage.run)
+    saved_remove_parser = saved_subparsers.add_parser("remove", help="remove a saved job")
+    saved_remove_parser.add_argument("object_id")
+    saved_remove_parser.add_argument("--yes", action="store_true")
+    saved_remove_parser.set_defaults(handler=saved_jobs_remove.run)
+    cache_parser = subparsers.add_parser("cache", help="manage anonymous read cache")
+    cache_subparsers = cache_parser.add_subparsers(dest="cache_command", required=True)
+    cache_purge_parser = cache_subparsers.add_parser("purge", help="remove cached anonymous reads")
+    cache_purge_parser.set_defaults(handler=cache_purge)
+    return parser
+
+
+def cache_purge(argv=None, json_output: bool = False) -> int:
+    """Purge all anonymous cache files."""
+    CacheStore(active_cache_root()).purge()
+    print("Cache purged")
+    return 0
+
+
+def main(argv: list[str] | None = None) -> None:
+    """Run the command-line interface.
+
+    Args:
+        argv: Optional argv list; defaults to ``sys.argv[1:]``.
+    """
+    arguments = build_parser().parse_args(argv)
+    handler = getattr(arguments, "handler", None)
+    if handler is not None:
+        json_output = getattr(arguments, "json", False)
+        try:
+            raise SystemExit(handler(arguments, json_output))
+        except InvalidSearchState as error:
+            print(f"hiringcafe: {error}", file=sys.stderr)
+            raise SystemExit(2) from error
+        except ValueError as error:
+            print(f"hiringcafe: {error}", file=sys.stderr)
+            raise SystemExit(1) from error
+        except FirebaseAuthError as error:
+            print(f"hiringcafe: {error}", file=sys.stderr)
+            raise SystemExit(5) from error
+        except FirebaseTransportError as error:
+            print(f"hiringcafe: {error}", file=sys.stderr)
+            raise SystemExit(1) from error
+        except FirestoreError as error:
+            print(f"hiringcafe: {error}", file=sys.stderr)
+            raise SystemExit(1) from error
+        except HireCafeHTTPError as error:
+            print(f"hiringcafe: {error}", file=sys.stderr)
+            raise SystemExit(3 if error.status == 429 else 1) from error
+        except HireCafeTransportError as error:
+            print(f"hiringcafe: {error}", file=sys.stderr)
+            raise SystemExit(1) from error

hiringcafe_cli-0.1.4/src/hiringcafe_cli/auth.py

@@ -0,0 +1,95 @@
+"""Firebase authentication commands."""
+
+import getpass
+import json
+import os
+import sys
+from pathlib import Path
+
+from hiringcafe_cli.firebase import FirebaseClient
+from hiringcafe_cli.session import SessionStore
+
+
+def default_session_path() -> Path:
+    """Return the platform user config session path."""
+    config_home = os.environ.get("HIRINGCAFE_CONFIG_HOME")
+    if config_home:
+        return Path(config_home) / "session.json"
+    return Path.home() / ".config" / "hiringcafe-cli" / "session.json"
+
+
+def store() -> SessionStore:
+    """Create the session store using the selected configuration root."""
+    return SessionStore(default_session_path())
+
+
+def import_token(argv: object, json_output: bool = False) -> int:
+    """Import a refresh token through stdin or the nonprinting environment."""
+    token = sys.stdin.readline().strip() or os.environ.get("HIRINGCAFE_REFRESH_TOKEN", "")
+    if not token:
+        print("hiringcafe: no refresh token provided on stdin or HIRINGCAFE_REFRESH_TOKEN", file=sys.stderr)
+        return 2
+    credentials = FirebaseClient().refresh(token)
+    store().save(credentials["refreshToken"])
+    print("Authenticated Firebase session saved")
+    return 0
+
+
+def login_email(argv: object, json_output: bool = False) -> int:
+    """Exchange Firebase email/password credentials once and save only the refresh token."""
+    password = os.environ.get("HIRINGCAFE_PASSWORD") or getpass.getpass("Firebase password: ")
+    credentials = FirebaseClient().login_with_password(argv.email, password)
+    del password
+    store().save(credentials["refreshToken"])
+    print("Authenticated Firebase session saved")
+    return 0
+
+
+def status(argv: object, json_output: bool = False) -> int:
+    """Report whether the stored Firebase credential can obtain an ID token.
+
+    Args:
+        argv: Unused CLI namespace.
+        json_output: Whether stdout must be machine-readable.
+
+    Returns:
+        Exit code 0 when usable, 4 when no session exists.
+    """
+    session = store().load()
+    if session is None:
+        if json_output:
+            print(json.dumps({"version": 1, "authenticated": False}, separators=(",", ":")))
+        else:
+            print("No stored credential", file=sys.stderr)
+        return 4
+    FirebaseClient().refresh(session.refresh_token)
+    if json_output:
+        payload = json.dumps(
+            {"version": 1, "authenticated": True},
+            separators=(",", ":"),
+        )
+        print(payload)
+    else:
+        print("Authenticated")
+    return 0
+
+
+def logout(argv: object, json_output: bool = False) -> int:
+    """Delete the local Firebase session.
+
+    Args:
+        argv: Unused CLI namespace.
+        json_output: Unused; logout output remains intentionally human-only.
+
+    Returns:
+        Exit code 0 after local credential removal.
+    """
+    session_store = store()
+    had_session = session_store.load() is not None
+    try:
+        session_store.delete()
+    except OSError as error:
+        print(f"hiringcafe: cannot remove session: {error}", file=sys.stderr)
+        return 1
+    print("Local Firebase session removed" if had_session else "No local Firebase session")
+    return 0