discolike-cli 0.3.1__tar.gz → 0.4.0__tar.gz

{discolike_cli-0.3.1 → discolike_cli-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: discolike-cli
-Version: 0.3.1
+Version: 0.4.0
 Summary: Official CLI for the DiscoLike API
 Project-URL: Homepage, https://www.discolike.com
 Project-URL: Documentation, https://docs.discolike.com
@@ -25,7 +25,7 @@ Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Utilities
 Classifier: Typing :: Typed
 Requires-Python: >=3.10
-Requires-Dist: discolike==0.3.1
+Requires-Dist: discolike==0.4.0
 Requires-Dist: rich>=13.0
 Requires-Dist: typer>=0.12
 Description-Content-Type: text/markdown
@@ -67,12 +67,25 @@ discolike company data stripe.com
 discolike extract https://stripe.com/enterprise
 ```
 
-Top-level commands: `discover`, `count`, `match`, `extract`, `validate-icp`, `append`, `segment` — plus `auth`, `company`, `contacts`, `discogen`, `queries`, `account`, `search-providers`, and `llm-providers` command groups.
+Top-level commands: `discover`, `count`, `match`, `extract`, `validate-icp`, `append`, `segment` — plus `auth`, `bulk`, `company`, `contacts`, `discogen`, `queries`, `account`, `search-providers`, and `llm-providers` command groups.
+
+### Volume pulls
+
+`discolike bulk` walks past the 10,000-per-search ceiling and pulls contacts for a whole domain list into one CSV, with checkpoint and resume:
+
+```bash
+discolike bulk companies --params-file form.json --max-companies 50000 --run-name agencies --out companies.csv
+discolike bulk estimate  --domains-file companies.csv --per-company 10          # free size check
+discolike bulk contacts  --domains-file companies.csv --per-company 10 --summary "growth marketing" --out contacts.csv
+```
+
+`companies` saves each page as an exclusion list (`<run-name>-round-N`) and excludes it from the next page; rerunning with the same `--out` resumes from the CSV. `contacts` slices the domain list at `10000 / per-company` domains per call and records finished slices in `<out>.checkpoint`. Both keep one call in flight under `--rate-limit` (default 10/min, the Pro rate on `/discover` and `/contacts`), retry on 429/5xx, and print a JSON summary at the end. Filters come from `--params-file`, `--param` and the common flags; the paging fields are managed for you.
 
 ### Conventions
 
 - Results print as JSON to stdout; errors print as JSON (`error`, `message`, `status_code`) to stderr.
 - Pass `--format table` for a human-readable table — used automatically when stdout is a TTY.
+- Volume inputs come from files: `--domains-file companies.csv` (a `domain` column, or one domain per line) on `queries create-exclusion-list`, `contacts discover|search|count|generate`, `discogen run` and `validate-icp`; `--params-file form.json` (a JSON object of API parameter names, e.g. an app form) on `discover`, `count` and `contacts discover|search|count`; `--exclude-domains-file` on `discover`. Precedence: file < `--param` < flags.
 - Async endpoints (`match --file`, `discogen run`, `discogen run-personas`, `segment`, `validate-icp`) take `--wait` to block until the job finishes. Without it, you get a `task_id` back to poll with `discolike discogen status <task_id> --family <family>`. `append` is synchronous — it returns enriched rows directly (or writes CSV bytes to `--output`).
 
 ### Exit codes

{discolike_cli-0.3.1 → discolike_cli-0.4.0}/README.md

@@ -35,12 +35,25 @@ discolike company data stripe.com
 discolike extract https://stripe.com/enterprise
 ```
 
-Top-level commands: `discover`, `count`, `match`, `extract`, `validate-icp`, `append`, `segment` — plus `auth`, `company`, `contacts`, `discogen`, `queries`, `account`, `search-providers`, and `llm-providers` command groups.
+Top-level commands: `discover`, `count`, `match`, `extract`, `validate-icp`, `append`, `segment` — plus `auth`, `bulk`, `company`, `contacts`, `discogen`, `queries`, `account`, `search-providers`, and `llm-providers` command groups.
+
+### Volume pulls
+
+`discolike bulk` walks past the 10,000-per-search ceiling and pulls contacts for a whole domain list into one CSV, with checkpoint and resume:
+
+```bash
+discolike bulk companies --params-file form.json --max-companies 50000 --run-name agencies --out companies.csv
+discolike bulk estimate  --domains-file companies.csv --per-company 10          # free size check
+discolike bulk contacts  --domains-file companies.csv --per-company 10 --summary "growth marketing" --out contacts.csv
+```
+
+`companies` saves each page as an exclusion list (`<run-name>-round-N`) and excludes it from the next page; rerunning with the same `--out` resumes from the CSV. `contacts` slices the domain list at `10000 / per-company` domains per call and records finished slices in `<out>.checkpoint`. Both keep one call in flight under `--rate-limit` (default 10/min, the Pro rate on `/discover` and `/contacts`), retry on 429/5xx, and print a JSON summary at the end. Filters come from `--params-file`, `--param` and the common flags; the paging fields are managed for you.
 
 ### Conventions
 
 - Results print as JSON to stdout; errors print as JSON (`error`, `message`, `status_code`) to stderr.
 - Pass `--format table` for a human-readable table — used automatically when stdout is a TTY.
+- Volume inputs come from files: `--domains-file companies.csv` (a `domain` column, or one domain per line) on `queries create-exclusion-list`, `contacts discover|search|count|generate`, `discogen run` and `validate-icp`; `--params-file form.json` (a JSON object of API parameter names, e.g. an app form) on `discover`, `count` and `contacts discover|search|count`; `--exclude-domains-file` on `discover`. Precedence: file < `--param` < flags.
 - Async endpoints (`match --file`, `discogen run`, `discogen run-personas`, `segment`, `validate-icp`) take `--wait` to block until the job finishes. Without it, you get a `task_id` back to poll with `discolike discogen status <task_id> --family <family>`. `append` is synchronous — it returns enriched rows directly (or writes CSV bytes to `--output`).
 
 ### Exit codes

{discolike_cli-0.3.1 → discolike_cli-0.4.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "discolike-cli"
-version = "0.3.1"
+version = "0.4.0"
 description = "Official CLI for the DiscoLike API"
 readme = "README.md"
 license = "MIT"
@@ -12,7 +12,7 @@ license-files = ["LICENSE"]
 requires-python = ">=3.10"
 authors = [{ name = "DiscoLike", email = "support@discolike.com" }]
 dependencies = [
-  "discolike==0.3.1",
+  "discolike==0.4.0",
   "typer>=0.12",
   "rich>=13.0",
 ]
@@ -34,7 +34,7 @@ classifiers = [
 ]
 
 [project.scripts]
-discolike = "discolike_cli.main:app"
+discolike = "discolike_cli.main:run"
 
 [project.urls]
 Homepage = "https://www.discolike.com"

discolike_cli-0.4.0/src/discolike_cli/_help.py

@@ -0,0 +1,292 @@
+"""Help-text epilogs that spell out the CLI's output contract for agents and scripts.
+
+Every constant here is plain text (no Rich markup) so it renders identically in a
+terminal, in a pipe, and in a test assertion. Response shapes mirror the SDK models in
+``discolike.resources``; keep them in sync when a model changes.
+"""
+
+from __future__ import annotations
+
+import textwrap
+
+import typer
+from typer._click import Context
+from typer._click import HelpFormatter
+from typer.core import TyperCommand
+from typer.core import TyperGroup
+
+from discolike._config import ENV_API_KEY
+from discolike._config import config_path
+
+EPILOG_INDENT = " "
+
+
+def _echo_verbatim(epilog: str) -> None:
+    # Typer's rich formatter reflows epilog paragraphs into prose, which destroys the
+    # aligned tables below. Print the epilog ourselves, exactly as written.
+    typer.echo(textwrap.indent(epilog.rstrip("\n"), EPILOG_INDENT))
+
+
+class ContractCommand(TyperCommand):
+    """A command whose epilog is printed verbatim, not reflowed."""
+
+    def format_help(self, ctx: Context, formatter: HelpFormatter) -> None:
+        epilog, self.epilog = self.epilog, None
+        try:
+            super().format_help(ctx, formatter)
+        finally:
+            self.epilog = epilog
+        if epilog:
+            _echo_verbatim(epilog)
+
+
+class ContractGroup(TyperGroup):
+    """A command group whose epilog is printed verbatim, not reflowed."""
+
+    def format_help(self, ctx: Context, formatter: HelpFormatter) -> None:
+        epilog, self.epilog = self.epilog, None
+        try:
+            super().format_help(ctx, formatter)
+        finally:
+            self.epilog = epilog
+        if epilog:
+            _echo_verbatim(epilog)
+
+
+_CONFIG_PATH_HINT = "$XDG_CONFIG_HOME/discolike/config.json (default ~/.config/discolike/config.json)"
+
+MAIN_EPILOG = f"""\
+Output contract:
+  Success      JSON on stdout, exit 0. JSON is the default whenever stdout is not a
+               TTY; --format json forces it and --format table renders a table for
+               humans. Progress lines from --wait go to stderr only.
+  Failure      {{"error", "code", "message", "status_code", "exit_code"}} on stderr
+               with a non-zero exit code. Branch on "code" (stable) or the exit code;
+               "error" is the SDK exception class name. rate_limited adds "retry_after".
+  Determinism  No spinners, colors, or prompts on stdout when piped.
+
+Exit codes:
+  0  success
+  1  server_error, job_failed, job_timeout, or any other unrecoverable error
+  2  validation_error   input rejected before or by the API (bad flag, enum, range)
+  3  auth_required      no credential found: run `discolike auth login`
+     auth_invalid       credential rejected (401/403); plan_access needs a higher plan
+  4  rate_limited       HTTP 429; wait "retry_after" seconds, then retry
+  5  network_error      could not reach the API
+  6  not_found          HTTP 404
+
+Environment:
+  {ENV_API_KEY}   API key; overrides the config file written by `discolike auth login`.
+  Config file          {_CONFIG_PATH_HINT}
+                       (resolved now: {config_path()})
+
+Examples:
+  $ discolike count --country DE --phrase-match "managed detection" --format json | jq .count
+  $ discolike discover --icp-prompt "cybersecurity for SMBs" --max-records 100 --format json | jq -r '.[].domain'
+  $ discolike validate-icp --icp "sells to hospitals" --domain a.com --domain b.com --wait --format json | jq '.'
+"""
+
+_COMPANY_ROW = """\
+    {"domain": <string>, "name": <string>, "similarity": <0-1>, "score": <int>,
+     "description": <string>, "employees": <string>, "revenue_range": <string>,
+     "address": {"city", "state", "country"}, "industry_groups": {<name>: <weight>},
+     "business_model": {<name>: <weight>}, "mx_provider": <string>, ...}"""
+
+_JOB_SUBMITTED = """\
+  Without --wait:
+    {"task_id": <string>, "task_family": <string>, "hint": "poll with: discolike discogen status ..."}"""
+
+_JOB_ERRORS = """\
+Common errors:
+  validation_error (exit 2)  bad flag value, empty domain list, or an unknown --model.
+  auth_required    (exit 3)  no credential; run `discolike auth login`.
+  plan_access      (exit 3)  the plan does not include this job type.
+  job_failed       (exit 1)  the job finished with an error (only with --wait).
+  job_timeout      (exit 1)  --timeout elapsed before the job finished; poll with `discolike discogen status`."""
+
+_SEARCH_ERRORS = """\
+Common errors:
+  validation_error (exit 2)  unknown filter value, bad range, or more than 10 seed domains.
+  auth_required    (exit 3)  no credential; run `discolike auth login`.
+  plan_access      (exit 3)  the plan does not allow this filter or record count.
+  rate_limited     (exit 4)  HTTP 429; retry after "retry_after" seconds."""
+
+COMMAND_EPILOGS: dict[str, str] = {
+    "discover": f"""\
+Output (success, exit 0):
+  [
+{_COMPANY_ROW}
+  ]
+  One row per matched company, ranked by similarity. Billed per 1,000 new records;
+  records seen in the last 90 days are free. Count first: `discolike count` is free.
+
+{_SEARCH_ERRORS}
+""",
+    "count": f"""\
+Output (success, exit 0):
+  {{"count": <int>}}
+  Free. Same filters as `discover`; run it before any large pull.
+
+{_SEARCH_ERRORS}
+""",
+    "match": """\
+Output (success, exit 0):
+  Single (--name):
+    {"query": {"name", "country", "state", "city", "zip", "phones"},
+     "matches": [{"domain": <string>, "name": <string>, "match_confidence": <0-100>, ...}]}
+  Bulk (--file) without --wait:
+    {"task_id": <string>, "task_family": <string>, "hint": <string>}
+  Bulk with --wait: one row per input row; rows the backend could not process carry
+  "match_error": "search_failed", which is not the same as no match.
+
+Common errors:
+  validation_error (exit 2)  neither --name nor --file given, or a named column is missing.
+  auth_required    (exit 3)  no credential; run `discolike auth login`.
+  job_timeout      (exit 1)  --timeout elapsed on a bulk match; poll with `discolike discogen status`.
+""",
+    "append": """\
+Output (success, exit 0):
+  JSON (default): [{"domain": <string>, <dataset fields>...}] one row per input row.
+  --csv --output FILE: {"written": <path>, "bytes": <int>} and the CSV is on disk.
+  Datasets: bizdata, domain_status, redirects, growth, vendors, subdomains.
+  Up to 10,000 rows per request; billed per new company record.
+
+Common errors:
+  validation_error (exit 2)  missing --domain-column, unknown --dataset, or --csv without --output.
+  auth_required    (exit 3)  no credential; run `discolike auth login`.
+  plan_access      (exit 3)  a requested dataset is not on the plan.
+""",
+    "validate-icp": f"""\
+Output (success, exit 0):
+{_JOB_SUBMITTED}
+  With --wait: the results object keyed by domain:
+    {{<domain>: {{"Fit": "Yes"|"No", "Confidence": "high"|"medium"|"low", "Reasoning": <string>}}, ...}}
+  Runs on the account's own LLM provider key.
+  With --integration-id native-icp: DiscoLike's own ICP-fit model, no LLM key or cost and no
+  web search. Keys become "ICP Fit" ("Yes"|"No" at a 0.50 threshold on the score), "ICP Score"
+  (the calibrated probability, 0.00-1.00 as a string) and "Reasoning", always null there: the
+  model returns a score, not an explanation. A 400 when the ICP text yields no Mandatory /
+  Reject if / Nice-to-have prompt, a 503 when no ICP-fit engine is available.
+
+{_JOB_ERRORS}
+""",
+    "segment": f"""\
+Output (success, exit 0):
+{_JOB_SUBMITTED}
+  With --wait: one BizData row per active domain, plus its cluster:
+    [{{"domain", "name", "score", "segment_id": <int, -1 = unclustered>,
+      "segment_description": <string>, "probability": <0-1>, ...}}]
+  Closed or unindexed input domains are omitted.
+
+{_JOB_ERRORS}
+""",
+    "extract": """\
+Output (success, exit 0):
+  {"text": <string>, "language": <ISO 639-1>}
+  Fetches the page live; use it to confirm a seed domain is the right company.
+
+Common errors:
+  validation_error (exit 2)  neither a URL argument nor --domain given.
+  auth_required    (exit 3)  no credential; run `discolike auth login`.
+  not_found        (exit 6)  the page could not be fetched.
+""",
+    "signup": """\
+Output (success, exit 0):
+  {"status": <string>, "email": <string>, "org_domain": <string>,
+   "org_status": <string>, "next_step": <string>}
+  No credential is returned. Relay "next_step" to the person: they confirm by email,
+  log in, pick a plan, then run `discolike auth login`. No login is needed for this call.
+
+Common errors:
+  validation_error (exit 2)  free-mail or disposable email domain, or a missing name.
+  error            (exit 1)  HTTP 409: the account already exists; send them to log in.
+""",
+    "contacts search": """\
+Output (success, exit 0):
+  [{"persona_id": <int>, "domain": <string>, "name": <string>, "title": <string>,
+    "email": <string>, ...}]
+  Billed per new contact record. `discolike contacts count` with the same filters is free.
+
+Common errors:
+  validation_error (exit 2)  unknown seniority/department value or a bad range.
+  auth_required    (exit 3)  no credential; run `discolike auth login`.
+  plan_access      (exit 3)  contacts are not included on the plan.
+""",
+    "contacts generate": f"""\
+Output (success, exit 0):
+{_JOB_SUBMITTED}
+  With --wait: results keyed by domain, zero or more candidate rows each:
+    {{<domain>: [{{"name", "title", "department", "seniority", "email", "linkedin_url",
+      "skills", "phone": [{{"phone", "type"}}], "email_pattern", "email_pattern_confidence",
+      "email_pattern_guess"}}], ...}}
+  Rows are candidates; email is set only when publicly verifiable.
+  Runs live web search on the account's own LLM and search provider keys; no platform billing.
+
+{_JOB_ERRORS}
+""",
+    "discogen run": f"""\
+Output (success, exit 0):
+{_JOB_SUBMITTED}
+  With --wait: one entry per domain with the model's structured answer to --query.
+  Send the whole list in one call; parallel jobs share the provider key and rate-limit each other.
+
+{_JOB_ERRORS}
+""",
+    "discogen status": """\
+Output (success, exit 0):
+  {"status": "pending"|"running"|"completed"|"failed", "progress": <0-100>,
+   "results": <any>, "warnings": [<string>], "estimated_cost": <float>,
+   "cost_metadata": {<provider/model>: {...}, "search_provider": {...}}}
+  "results" is null until the job completes. Pass --family for non-DiscoGen jobs.
+
+Common errors:
+  validation_error (exit 2)  unknown --family value.
+  auth_required    (exit 3)  no credential; run `discolike auth login`.
+  not_found        (exit 6)  no job with that task id in that family.
+""",
+    "queries create-exclusion-list": """\
+Output (success, exit 0):
+  {"query_id": <string>, "query_name": <string>, "action": <string>,
+   "domain_count": <int>, "persona_id_count": <int>, "row_count": <int>, "tags": [<string>]}
+  Pass "query_id" as --exclusion-query-id (or --inclusion-query-id) on the next discover.
+  Minimum 20 domains; lists hold up to 250,000 domains on every plan.
+
+Common errors:
+  validation_error (exit 2)  fewer than 20 domains, or a missing --name.
+  auth_required    (exit 3)  no credential; run `discolike auth login`.
+""",
+    "auth login": """\
+Output (success, exit 0):
+  Browser (default): {"logged_in": true, "method": "oauth", "expires_at": <ISO 8601>}
+  --api-key KEY:     {"logged_in": true, "source": "api_key"}
+  The credential is saved to the config file; later commands read it automatically.
+  Progress lines (the URL to open, browser wait) go to stderr; only the JSON above is on stdout.
+  Headless: --no-browser prints the URL to open; --port pins the loopback port for SSH.
+
+Common errors:
+  auth_invalid     (exit 3)  the API key was rejected.
+  error            (exit 1)  {"error": "LoginError", ...}: timeout, denied consent, or state mismatch.
+""",
+    "auth status": """\
+Output (success, exit 0):
+  API key: {"source": "option"|"env"|"config", "method": "api_key", "api_key": <masked>, "valid": true}
+  OAuth:   {"source": "config", "method": "oauth", "expires_at": <ISO 8601>, "expired": <bool>, "valid": true}
+  Exit 0 here is the whole proof that the CLI is signed in.
+
+Common errors:
+  auth_required    (exit 3)  no credential anywhere; run `discolike auth login`.
+  auth_invalid     (exit 3)  the stored credential no longer verifies; log in again.
+""",
+    "account usage": """\
+Output (success, exit 0):
+  {"requests_mtd": <int>, "records_mtd": <int>, "spend_mtd": <float>}
+  Month-to-date. Report it before any paid flow so the person knows the baseline.
+
+Common errors:
+  auth_required    (exit 3)  no credential; run `discolike auth login`.
+""",
+}
+
+
+def epilog(name: str) -> str:
+    return COMMAND_EPILOGS[name]

discolike_cli-0.4.0/src/discolike_cli/_inputs.py

@@ -0,0 +1,64 @@
+"""File-backed inputs for volume flows: domain lists and whole-request JSON."""
+
+from __future__ import annotations
+
+import csv
+import json
+import pathlib
+from typing import Any
+
+import typer
+
+DOMAIN_COLUMN = "domain"
+WWW_PREFIX = "www."
+
+
+def read_domains_file(path: pathlib.Path) -> list[str]:
+    """CSV with a ``domain`` column, or one domain per line (first column when no header).
+
+    Domains are stripped, lower-cased, ``www.``-less and de-duplicated in file order.
+    """
+    try:
+        with path.open(newline="") as handle:
+            rows = list(csv.reader(handle))
+    except FileNotFoundError as exc:
+        raise typer.BadParameter(f"domains file not found: {path}") from exc
+    except (OSError, UnicodeDecodeError) as exc:
+        raise typer.BadParameter(f"domains file {path} could not be read: {exc}") from exc
+    header = [cell.strip().lower() for cell in rows[0]] if rows else []
+    column = header.index(DOMAIN_COLUMN) if DOMAIN_COLUMN in header else 0
+    body = rows[1:] if DOMAIN_COLUMN in header else rows
+    seen: set[str] = set()
+    domains: list[str] = []
+    for row in body:
+        if column >= len(row):
+            continue
+        domain = row[column].strip().lower().removeprefix(WWW_PREFIX)
+        if domain and domain not in seen:
+            seen.add(domain)
+            domains.append(domain)
+    if not domains:
+        raise typer.BadParameter(f"domains file has no domains: {path}")
+    return domains
+
+
+def read_params_file(path: pathlib.Path) -> dict[str, Any]:
+    """JSON object of API parameter names, e.g. an app form copied over verbatim."""
+    try:
+        loaded = json.loads(path.read_text())
+    except FileNotFoundError as exc:
+        raise typer.BadParameter(f"params file not found: {path}") from exc
+    except (OSError, UnicodeDecodeError) as exc:
+        raise typer.BadParameter(f"params file {path} could not be read: {exc}") from exc
+    except json.JSONDecodeError as exc:
+        raise typer.BadParameter(f"params file {path} must contain valid JSON: {exc}") from exc
+    if not isinstance(loaded, dict):
+        raise typer.BadParameter(f"params file {path} must contain a JSON object")
+    return loaded
+
+
+def merge_domains(inline: list[str] | None, file: pathlib.Path | None) -> list[str] | None:
+    """Inline ``--domain`` values first, then the file's, or ``None`` when neither was given."""
+    if file is None:
+        return inline
+    return [*(inline or []), *read_domains_file(file)]

{discolike_cli-0.3.1 → discolike_cli-0.4.0}/src/discolike_cli/_output.py

@@ -16,12 +16,16 @@ import typer
 from rich.console import Console
 from rich.table import Table
 
+from discolike._config import NO_CREDENTIAL_MESSAGE
 from discolike._exceptions import APIConnectionError
 from discolike._exceptions import AuthenticationError
 from discolike._exceptions import DiscolikeError
+from discolike._exceptions import JobFailedError
+from discolike._exceptions import JobTimeoutError
 from discolike._exceptions import NotFoundError
 from discolike._exceptions import PlanAccessError
 from discolike._exceptions import RateLimitError
+from discolike._exceptions import ServerError
 from discolike._exceptions import ValidationError
 from discolike._models import DiscolikeModel
 
@@ -40,6 +44,30 @@ EXIT_CODES: dict[type, int] = {
 }
 DEFAULT_EXIT_CODE = 1
 
+# Stable, snake_case error codes for agents and scripts to branch on. The class
+# name in `error` is kept for backwards compatibility; `code` is the contract.
+ERROR_CODES: dict[type, str] = {
+    ValidationError: "validation_error",
+    AuthenticationError: "auth_invalid",
+    PlanAccessError: "plan_access",
+    RateLimitError: "rate_limited",
+    APIConnectionError: "network_error",
+    NotFoundError: "not_found",
+    ServerError: "server_error",
+    JobFailedError: "job_failed",
+    JobTimeoutError: "job_timeout",
+}
+DEFAULT_ERROR_CODE = "error"
+AUTH_REQUIRED_CODE = "auth_required"
+
+
+def error_code(exc: DiscolikeError) -> str:
+    # The SDK raises the same exception class both when no credential exists and when a stored
+    # OAuth credential fails to refresh; only the former is "run `discolike auth login`" territory.
+    if isinstance(exc, AuthenticationError) and str(exc) == NO_CREDENTIAL_MESSAGE:
+        return AUTH_REQUIRED_CODE
+    return ERROR_CODES.get(type(exc), DEFAULT_ERROR_CODE)
+
 
 class _JobStatusLike(Protocol):
     results: Any
@@ -111,15 +139,18 @@ def emit(data: Any, *, fmt: str | None = None) -> None:  # noqa: ANN401 -- accep
 
 
 def fail(exc: DiscolikeError) -> typer.Exit:
+    exit_code = EXIT_CODES.get(type(exc), DEFAULT_EXIT_CODE)
     payload: dict[str, Any] = {
         "error": type(exc).__name__,
+        "code": error_code(exc),
         "message": str(exc),
         "status_code": exc.status_code,
+        "exit_code": exit_code,
     }
     if isinstance(exc, RateLimitError) and exc.retry_after is not None:
         payload["retry_after"] = exc.retry_after
     print(json.dumps(payload), file=sys.stderr)
-    return typer.Exit(code=EXIT_CODES.get(type(exc), DEFAULT_EXIT_CODE))
+    return typer.Exit(code=exit_code)
 
 
 def _accepts_list(model: type[pydantic.BaseModel], name: str) -> bool:

{discolike_cli-0.3.1 → discolike_cli-0.4.0}/src/discolike_cli/account.py

@@ -2,6 +2,8 @@ from __future__ import annotations
 
 import typer
 
+from discolike_cli._help import ContractCommand
+from discolike_cli._help import epilog
 from discolike_cli._output import emit
 from discolike_cli._output import handle_errors
 
@@ -10,7 +12,7 @@ FORMAT_HELP = "Output format: json or table (table auto-selected on a TTY; falls
 app = typer.Typer(help="Account usage and quota.")
 
 
-@app.command("usage")
+@app.command("usage", cls=ContractCommand, epilog=epilog("account usage"))
 @handle_errors
 def usage_command(
     ctx: typer.Context,

{discolike_cli-0.3.1 → discolike_cli-0.4.0}/src/discolike_cli/auth.py

@@ -34,6 +34,8 @@ from discolike._oauth import build_authorization_url
 from discolike._oauth import discover
 from discolike._oauth import exchange_code
 from discolike._oauth import register_client
+from discolike_cli._help import ContractCommand
+from discolike_cli._help import epilog
 from discolike_cli._loopback import CallbackServer
 from discolike_cli._output import emit
 from discolike_cli._output import handle_errors
@@ -225,10 +227,10 @@ def _api_key_login(ctx: typer.Context, *, api_key: str | None) -> None:
     key = api_key or passed_globally or typer.prompt("API key", hide_input=True)
     _verify(ctx, api_key=key)
     save_config({"auth_method": AUTH_METHOD_API_KEY, "api_key": key})
-    print(json.dumps({"logged_in": True, "source": AUTH_METHOD_API_KEY}), file=sys.stderr)
+    emit({"logged_in": True, "source": AUTH_METHOD_API_KEY})
 
 
-@app.command()
+@app.command(cls=ContractCommand, epilog=epilog("auth login"))
 @handle_errors
 def login(
     ctx: typer.Context,
@@ -263,13 +265,10 @@ def login(
     credential = _oauth_login(ctx, open_browser=not no_browser, port=port)
     _verify(ctx, auth=credential)
     save_credential(credential)
-    print(
-        json.dumps({"logged_in": True, "method": AUTH_METHOD_OAUTH, "expires_at": _iso(credential.expires_at)}),
-        file=sys.stderr,
-    )
+    emit({"logged_in": True, "method": AUTH_METHOD_OAUTH, "expires_at": _iso(credential.expires_at)})
 
 
-@app.command()
+@app.command(cls=ContractCommand, epilog=epilog("auth status"))
 @handle_errors
 def status(ctx: typer.Context) -> None:
     """Show which credential is in use (option, env, or config) and verify it against the API."""