tarnished-cli 0.1.2__tar.gz → 0.1.4__tar.gz

{tarnished_cli-0.1.2 → tarnished_cli-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tarnished-cli
-Version: 0.1.2
+Version: 0.1.4
 Summary: Agent-first CLI for Tarnished
 Requires-Python: >=3.12
 Requires-Dist: email-validator>=2.0.0
@@ -28,10 +28,23 @@ Alternative:
 pipx install tarnished-cli
 ```
 
+Homebrew convenience path:
+
+```bash
+brew tap markoonakic/tap
+brew install tarnished-cli
+```
+
+For agents and automation, keep using:
+
+```bash
+uv tool install tarnished-cli
+```
+
 Install from a built wheel before PyPI publication:
 
 ```bash
-uv tool install ./dist/tarnished_cli-0.1.2-py3-none-any.whl
+uv tool install ./dist/tarnished_cli-0.1.4-py3-none-any.whl
 ```
 
 ## OpenClaw / Agent Install
@@ -45,7 +58,7 @@ uv tool install tarnished-cli
 Version-pinned:
 
 ```bash
-uv tool install 'tarnished-cli==0.1.2'
+uv tool install 'tarnished-cli==0.1.4'
 ```
 
 Then run:

{tarnished_cli-0.1.2 → tarnished_cli-0.1.4}/README.md

@@ -16,10 +16,23 @@ Alternative:
 pipx install tarnished-cli
 ```
 
+Homebrew convenience path:
+
+```bash
+brew tap markoonakic/tap
+brew install tarnished-cli
+```
+
+For agents and automation, keep using:
+
+```bash
+uv tool install tarnished-cli
+```
+
 Install from a built wheel before PyPI publication:
 
 ```bash
-uv tool install ./dist/tarnished_cli-0.1.2-py3-none-any.whl
+uv tool install ./dist/tarnished_cli-0.1.4-py3-none-any.whl
 ```
 
 ## OpenClaw / Agent Install
@@ -33,7 +46,7 @@ uv tool install tarnished-cli
 Version-pinned:
 
 ```bash
-uv tool install 'tarnished-cli==0.1.2'
+uv tool install 'tarnished-cli==0.1.4'
 ```
 
 Then run:

{tarnished_cli-0.1.2 → tarnished_cli-0.1.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "tarnished-cli"
-version = "0.1.2"
+version = "0.1.4"
 description = "Agent-first CLI for Tarnished"
 readme = "README.md"
 requires-python = ">=3.12"

tarnished_cli-0.1.4/skills/tarnished-cli/SKILL.md

@@ -0,0 +1,171 @@
+---
+name: tarnished-cli
+description: Use this skill whenever the user wants to operate Tarnished through the CLI, inspect or change applications, job leads, rounds, profile, settings, analytics, import/export, or admin data, or automate Tarnished from an agent. Prefer this skill even for general Tarnished operational requests if the work should happen through the `tarnished` command instead of the browser UI.
+---
+
+# Tarnished CLI
+
+Use the Tarnished CLI as the primary interface to Tarnished's server-backed product surface.
+
+The CLI covers the full server-backed Tarnished surface:
+
+- `auth`
+- `applications`
+- `job-leads`
+- `dashboard`
+- `analytics`
+- `statuses`
+- `round-types`
+- `rounds`
+- `profile`
+- `preferences`
+- `user-settings`
+- `export`
+- `import`
+- `admin`
+
+The CLI covers server-backed data/actions from the product. It does not reproduce browser-rendered presentation or browser-only behavior such as charts, modals, page navigation, extension popups, or DOM automation.
+
+## Preflight
+
+1. Check the CLI version:
+   - `tarnished --version`
+2. Check session state:
+   - `tarnished auth status --json`
+   - if not authenticated, use `tarnished auth --help` and run the appropriate `login` or `register` flow
+3. If the target environment is ambiguous, prefer explicit targeting:
+   - `--profile`
+   - `--base-url`
+
+## Operating Defaults
+
+- prefer `--json` for agent use.
+- prefer explicit `--profile` when more than one Tarnished environment may exist.
+- Prefer explicit `--base-url` when operating against a one-off instance.
+- Prefer structured `--body-file` JSON for writes instead of constructing many ad hoc flags.
+- Add `--yes` for destructive commands.
+- Use only when you need privileged access.
+  This applies to `tarnished admin ...`.
+
+## Core Workflows
+
+### Read Data
+
+Use read commands with `--json` whenever the output will be consumed by an agent.
+
+Common starting points:
+
+- Applications:
+  - `tarnished applications list --json`
+  - `tarnished statuses list --json`
+  - use `tarnished statuses list --json` before filtering applications by `status_id`
+  - `tarnished applications get <application-id> --json`
+- Job leads:
+  - `tarnished job-leads list --json`
+  - `tarnished job-leads get <job-lead-id> --json`
+- Dashboard and analytics:
+  - `tarnished dashboard summary --json`
+  - `tarnished analytics kpis --period 30d --json`
+  - `tarnished analytics weekly --period 30d --json`
+  - `tarnished analytics sankey --json`
+- Profile and settings:
+  - `tarnished auth whoami --json`
+  - `tarnished auth api-key show --json`
+  - `tarnished profile get --json`
+  - `tarnished dashboard summary --json`
+  - `tarnished user-settings get --json`
+  - `tarnished preferences get --json`
+
+If you need exact flags for a command group, use:
+
+- `tarnished <command> --help`
+
+### Write Data
+
+For create and update flows, prefer checked-in or generated JSON body files.
+
+Examples:
+
+- Create an application:
+  - `tarnished applications create --body-file create-application.json`
+- Extract and create an application from source text or URL:
+  - `tarnished applications extract --body-file extract-application.json`
+- Create a job lead:
+  - `tarnished job-leads create --body-file create-job-lead.json`
+- Convert a lead into an application:
+  - `tarnished job-leads convert <job-lead-id>`
+- Update a profile:
+  - `tarnished profile update --body-file profile-update.json`
+
+When changing data, keep commands explicit and avoid relying on interactive behavior.
+
+### Destructive Actions
+
+Destructive commands require deliberate confirmation.
+
+Examples:
+
+- `tarnished applications delete <application-id> --yes`
+- `tarnished job-leads delete <job-lead-id> --yes`
+- `tarnished admin users delete <user-id> --yes`
+
+Do not omit `--yes` in automated flows.
+
+### Admin Surface
+
+Treat `admin` as privileged.
+
+Use it only when the task genuinely requires administrative access.
+
+Common admin reads:
+
+- `tarnished admin stats --json`
+- `tarnished admin users list --json`
+- `tarnished admin applications list --json`
+- `tarnished admin ai-settings get --json`
+
+Common admin writes:
+
+- `tarnished admin users create --body-file admin-user.json`
+- `tarnished admin users update <user-id> --body-file admin-user-update.json`
+- `tarnished admin ai-settings update --body-file ai-settings.json`
+
+## Additional Surfaces
+
+The CLI also covers:
+
+- `rounds`
+- `round-types`
+- application CV / cover-letter flows
+- transcript and media upload/download flows
+- `export`
+- `import`
+- API key management via `tarnished auth api-key ...`
+
+Useful operator recipes:
+
+- Signed application document URLs:
+  - `tarnished applications cv url <application-id>`
+  - `tarnished applications cover-letter url <application-id>`
+- Round transcript and media flows:
+  - `tarnished rounds transcript upload <round-id> --file-path transcript.txt`
+  - `tarnished rounds media upload <round-id> --file-path interview.wav`
+  - `tarnished rounds transcript url <round-id>`
+  - `tarnished rounds media url <round-id>`
+- Import safety:
+  - `tarnished import validate <export-file>`
+  - `tarnished import run <export-file> --wait`
+
+Use command-group help for exact syntax:
+
+- `tarnished rounds --help`
+- `tarnished export --help`
+- `tarnished import --help`
+
+## Safety Rules
+
+- Prefer read commands first when you need to inspect state before mutating it.
+- Prefer `--json` whenever a downstream agent or tool will parse the output.
+- Prefer explicit environment targeting with `--profile` or `--base-url` rather than assuming the default target.
+- Do not use `admin` unless the task requires privileged operations.
+- Do not describe the CLI as reproducing browser UI behavior; it exposes server-backed data/actions, not browser-rendered presentation.

tarnished_cli-0.1.4/skills/tarnished-cli/evals/trigger-eval.json

@@ -0,0 +1,82 @@
+[
+  {
+    "query": "i need to see every application in my tarnished instance that is still in the applied stage and dump it as json so another agent can sort them by age",
+    "should_trigger": true
+  },
+  {
+    "query": "can you use tarnished to create a new application for ExampleCo from this body file i already prepared in /tmp/create-application.json and keep the output machine readable",
+    "should_trigger": true
+  },
+  {
+    "query": "my local job tracker on http://127.0.0.1:5577 has a lead i want converted into an application, please do it through the tarnished cli not the browser",
+    "should_trigger": true
+  },
+  {
+    "query": "check whether im logged into tarnished on the prod profile and if not tell me what auth command i should run next",
+    "should_trigger": true
+  },
+  {
+    "query": "pull the 30 day kpis and weekly analytics from tarnished as json because i want another script to compare my response rate week over week",
+    "should_trigger": true
+  },
+  {
+    "query": "i want to export my tarnished data before i mess with imports, use the cli and give me the safest command flow",
+    "should_trigger": true
+  },
+  {
+    "query": "use tarnished admin commands to list users on my self hosted instance and show me the output as json, dont click through the UI",
+    "should_trigger": true
+  },
+  {
+    "query": "there is a cv attached to application app-123 in tarnished and i need the signed download url through the cli",
+    "should_trigger": true
+  },
+  {
+    "query": "for my job tracker instance, add a new lead from /tmp/lead.json and then list the latest job leads back to me in json",
+    "should_trigger": true
+  },
+  {
+    "query": "i recorded an interview round and need to manage the round data, transcript, and media through tarnished commands instead of the site",
+    "should_trigger": true
+  },
+  {
+    "query": "can you inspect the Tarnished analytics experience and tell me whether the sankey chart is visually broken on mobile, even if you need to look at the browser rather than raw json",
+    "should_trigger": false
+  },
+  {
+    "query": "my Tarnished pipeline looks bad but i dont actually want commands run, i just want strategic advice on whether i should keep applying or pause for interview prep",
+    "should_trigger": false
+  },
+  {
+    "query": "use kubectl to inspect why the tarnished deployment in my homelab namespace keeps restarting and check pod logs, this is cluster debugging not cli usage",
+    "should_trigger": false
+  },
+  {
+    "query": "write release notes for Tarnished CLI 0.1.3 and mention the new analytics and import work, but do not run the tarnished command at all",
+    "should_trigger": false
+  },
+  {
+    "query": "i have a csv exported from Tarnished but i want you to analyze it with python and charts directly, not through the tarnished command",
+    "should_trigger": false
+  },
+  {
+    "query": "fix the React settings page in Tarnished where the API key form jumps around during loading, and only use the cli if you need sample data, the main task is frontend code",
+    "should_trigger": false
+  },
+  {
+    "query": "open the Tarnished browser extension popup and check whether autofill is working on this greenhouse form, so this is extension behavior not cli automation",
+    "should_trigger": false
+  },
+  {
+    "query": "show me how to install tarnished-cli with homebrew on a new machine and explain the setup, i dont need you to operate the CLI after that",
+    "should_trigger": false
+  },
+  {
+    "query": "i want a shell alias so zsh autocomplete works better for tarnished, this is terminal config work around the cli rather than actual Tarnished operations",
+    "should_trigger": false
+  },
+  {
+    "query": "please design a prettier dashboard for my job tracker with better spacing and color hierarchy, but do not use the CLI because this is a product design task",
+    "should_trigger": false
+  }
+]

{tarnished_cli-0.1.2 → tarnished_cli-0.1.4}/src/tarnished_cli/auth_storage.py

@@ -11,19 +11,15 @@ from pydantic import BaseModel
 
 from tarnished_cli.config import resolve_config_dir
 
-ACCESS_TOKEN_ENV = "TARNISHED_ACCESS_TOKEN"
-REFRESH_TOKEN_ENV = "TARNISHED_REFRESH_TOKEN"
 API_KEY_ENV = "TARNISHED_API_KEY"
 KEYRING_SERVICE = "tarnished-cli"
 
 
 class StoredAuth(BaseModel):
-    access_token: str | None = None
-    refresh_token: str | None = None
     api_key: str | None = None
 
     def is_empty(self) -> bool:
-        return not any([self.access_token, self.refresh_token, self.api_key])
+        return self.api_key is None
 
 
 def resolve_auth_path(profile: str = "default", config_dir: Path | None = None) -> Path:
@@ -36,16 +32,10 @@ def _keyring_account(profile: str = "default", config_dir: Path | None = None) -
 
 
 def _env_auth() -> StoredAuth | None:
-    access_token = os.getenv(ACCESS_TOKEN_ENV)
-    refresh_token = os.getenv(REFRESH_TOKEN_ENV)
     api_key = os.getenv(API_KEY_ENV)
-    if not any([access_token, refresh_token, api_key]):
+    if not api_key:
         return None
-    return StoredAuth(
-        access_token=access_token,
-        refresh_token=refresh_token,
-        api_key=api_key,
-    )
+    return StoredAuth(api_key=api_key)
 
 
 def _read_auth_file(path: Path) -> StoredAuth:

{tarnished_cli-0.1.2 → tarnished_cli-0.1.4}/src/tarnished_cli/client.py

@@ -1,7 +1,6 @@
 from __future__ import annotations
 
 import json
-from collections.abc import Callable
 from dataclasses import dataclass
 from importlib.metadata import PackageNotFoundError, version
 from pathlib import Path
@@ -9,8 +8,7 @@ from typing import Any, Literal
 
 import httpx
 
-AuthMode = Literal["none", "jwt", "api_key", "flexible"]
-TokenUpdateHook = Callable[[str, str], None]
+AuthMode = Literal["none", "api_key"]
 
 
 def _resolve_cli_version() -> str:
@@ -42,17 +40,11 @@ class TarnishedClient:
         self,
         *,
         base_url: str,
-        access_token: str | None = None,
-        refresh_token: str | None = None,
         api_key: str | None = None,
-        on_token_refresh: TokenUpdateHook | None = None,
         transport: httpx.BaseTransport | None = None,
     ) -> None:
         self.base_url = base_url.rstrip("/")
-        self.access_token = access_token
-        self.refresh_token = refresh_token
         self.api_key = api_key
-        self._on_token_refresh = on_token_refresh
         self._client = httpx.Client(
             base_url=self.base_url,
             follow_redirects=True,
@@ -82,8 +74,7 @@ class TarnishedClient:
         params: dict[str, Any] | None = None,
         json_body: dict[str, Any] | None = None,
         files: dict[str, Any] | None = None,
-        auth: AuthMode = "jwt",
-        allow_refresh: bool = True,
+        auth: AuthMode = "api_key",
     ) -> httpx.Response:
         response = self._client.request(
             method,
@@ -94,24 +85,6 @@ class TarnishedClient:
             headers=self._build_auth_headers(auth),
         )
 
-        if (
-            response.status_code == 401
-            and allow_refresh
-            and auth in {"jwt", "flexible"}
-            and self.access_token
-            and self.refresh_token
-        ):
-            self.refresh_session()
-            return self.request(
-                method,
-                path,
-                params=params,
-                json_body=json_body,
-                files=files,
-                auth=auth,
-                allow_refresh=False,
-            )
-
         if response.is_error:
             raise self._to_api_error(response)
 
@@ -122,7 +95,7 @@ class TarnishedClient:
         path: str,
         *,
         params: dict[str, Any] | None = None,
-        auth: AuthMode = "jwt",
+        auth: AuthMode = "api_key",
     ) -> Any:
         return self._decode_response(
             self.request("GET", path, params=params, auth=auth)
@@ -133,7 +106,7 @@ class TarnishedClient:
         path: str,
         *,
         body: dict[str, Any],
-        auth: AuthMode = "jwt",
+        auth: AuthMode = "api_key",
     ) -> Any:
         return self._decode_response(
             self.request("POST", path, json_body=body, auth=auth)
@@ -144,7 +117,7 @@ class TarnishedClient:
         path: str,
         *,
         body: dict[str, Any],
-        auth: AuthMode = "jwt",
+        auth: AuthMode = "api_key",
     ) -> Any:
         return self._decode_response(
             self.request("PATCH", path, json_body=body, auth=auth)
@@ -155,16 +128,16 @@ class TarnishedClient:
         path: str,
         *,
         body: dict[str, Any],
-        auth: AuthMode = "jwt",
+        auth: AuthMode = "api_key",
     ) -> Any:
         return self._decode_response(
             self.request("PUT", path, json_body=body, auth=auth)
         )
 
-    def delete(self, path: str, *, auth: AuthMode = "jwt") -> None:
+    def delete(self, path: str, *, auth: AuthMode = "api_key") -> None:
         self.request("DELETE", path, auth=auth)
 
-    def delete_json(self, path: str, *, auth: AuthMode = "jwt") -> Any:
+    def delete_json(self, path: str, *, auth: AuthMode = "api_key") -> Any:
         return self._decode_response(self.request("DELETE", path, auth=auth))
 
     def post_file_json(
@@ -174,9 +147,8 @@ class TarnishedClient:
         file_path: Path,
         field_name: str = "file",
         data: dict[str, Any] | None = None,
-        auth: AuthMode = "jwt",
+        auth: AuthMode = "api_key",
         content_type: str | None = None,
-        allow_refresh: bool = True,
     ) -> Any:
         with file_path.open("rb") as handle:
             file_tuple: tuple[str, Any] | tuple[str, Any, str]
@@ -192,24 +164,6 @@ class TarnishedClient:
                 headers=self._build_auth_headers(auth),
             )
 
-        if (
-            response.status_code == 401
-            and allow_refresh
-            and auth in {"jwt", "flexible"}
-            and self.access_token
-            and self.refresh_token
-        ):
-            self.refresh_session()
-            return self.post_file_json(
-                path,
-                file_path=file_path,
-                field_name=field_name,
-                data=data,
-                auth=auth,
-                content_type=content_type,
-                allow_refresh=False,
-            )
-
         if response.is_error:
             raise self._to_api_error(response)
 
@@ -220,62 +174,19 @@ class TarnishedClient:
         path: str,
         *,
         params: dict[str, Any] | None = None,
-        auth: AuthMode = "jwt",
+        auth: AuthMode = "api_key",
     ) -> tuple[bytes, httpx.Headers]:
         response = self.request("GET", path, params=params, auth=auth)
         return response.content, response.headers
 
-    def refresh_session(self) -> None:
-        if not self.refresh_token:
-            raise CLIError("This command requires login.")
-
-        response = self._client.post(
-            "/api/auth/refresh",
-            json={"refresh_token": self.refresh_token},
-        )
-        if response.is_error:
-            raise CLIError("Stored session expired. Run `tarnished auth login` again.")
-
-        payload = response.json()
-        access_token = payload.get("access_token")
-        refresh_token = payload.get("refresh_token")
-        if not access_token or not refresh_token:
-            raise CLIError("Refresh response did not include a full token pair.")
-
-        self.access_token = access_token
-        self.refresh_token = refresh_token
-        if self._on_token_refresh is not None:
-            self._on_token_refresh(access_token, refresh_token)
-
     def _build_auth_headers(self, auth: AuthMode) -> dict[str, str]:
-        headers: dict[str, str] = {}
-
         if auth == "none":
-            return headers
-
-        if auth == "jwt":
-            if not self.access_token:
-                raise CLIError(
-                    "This command requires login. Run `tarnished auth login`."
-                )
-            headers["Authorization"] = f"Bearer {self.access_token}"
-            return headers
-
-        if auth == "api_key":
-            if not self.api_key:
-                raise CLIError("This command requires an API key.")
-            headers["X-API-Key"] = self.api_key
-            return headers
-
-        if self.access_token:
-            headers["Authorization"] = f"Bearer {self.access_token}"
-            return headers
-
-        if self.api_key:
-            headers["X-API-Key"] = self.api_key
-            return headers
-
-        raise CLIError("This command requires authentication.")
+            return {}
+
+        if not self.api_key:
+            raise CLIError("This command requires an API key.")
+
+        return {"X-API-Key": self.api_key}
 
     def _decode_response(self, response: httpx.Response) -> Any:
         if response.status_code == 204 or not response.content:

{tarnished_cli-0.1.2 → tarnished_cli-0.1.4}/src/tarnished_cli/commands/admin.py

@@ -14,7 +14,16 @@ from tarnished_cli.models import (
 from tarnished_cli.output import emit_result, exit_for_error
 from tarnished_cli.state import get_state
 
-app = typer.Typer(help="Admin-only commands.")
+ADMIN_HELP = """Admin-only commands. Use only when you need privileged access.
+
+Examples:
+  tarnished admin stats --json
+  tarnished admin users list --json
+  tarnished admin ai-settings get --json
+"""
+
+
+app = typer.Typer(help=ADMIN_HELP)
 users_app = typer.Typer(help="Manage users.")
 applications_app = typer.Typer(help="Inspect all applications.")
 statuses_app = typer.Typer(help="Manage default statuses.")

{tarnished_cli-0.1.2 → tarnished_cli-0.1.4}/src/tarnished_cli/commands/analytics.py

@@ -8,7 +8,16 @@ from tarnished_cli.models import InsightsRequest
 from tarnished_cli.output import emit_result, exit_for_error
 from tarnished_cli.state import get_state
 
-app = typer.Typer(help="Read analytics data.")
+ANALYTICS_HELP = """Read analytics data.
+
+Examples:
+  tarnished analytics kpis --period 30d --json
+  tarnished analytics heatmap --year 2026 --json
+  tarnished analytics insights --body-file insights.json
+"""
+
+
+app = typer.Typer(help=ANALYTICS_HELP)
 
 
 @app.command("kpis")