Add a new CLI command

The CLI lives in src/jobtrack/cli.py. It's a typer app with seven commands today: add, list, show, open, status, note, tag. The pattern is consistent — follow it.

Hard rules

• Business logic goes in core.py, never in cli.py. The CLI parses args, calls a core function, formats output. If the new command needs new logic, add a function to core.py first and call it from the typer command.
• Use _resolve_or_exit(query) for any command that takes an <id|company> argument. It handles ambiguity (prints a numbered list and exits 1) and not-found (exits 1) uniformly. Don't reimplement.
• Format output with rich. Use the module-level console. Tables for lists, console.print_json for structured data, [green]...[/green] / [red]...[/red] for status messages.
• Exit codes: 0 success, 1 resolution/runtime failure, 2 bad input (usage error).

The pattern

1. Add a function to core.py if there's new business logic. Keep it pure (takes ids/values, returns or mutates via storage). Don't import typer or rich there.
2. Add the typer command in cli.py:

   @app.command("verb")
   def verb_cmd(
       query: str = typer.Argument(..., help="ID or company"),
       # ... other args ...
   ):
       """One-line help string — shown by `jobtrack verb --help`."""
       meta = _resolve_or_exit(query)
       result = core.<the_thing>(meta.id, ...)
       console.print(f"[green]Did the thing to[/green] {meta.id}")

3. Naming conflicts with Python builtins: the typer function name can shadow builtins (list, open, etc.) which makes for awkward Python. The existing pattern is to name the function <verb>_cmd and pass the verb as the first arg to @app.command():

   @app.command("list")
   def list_cmd(...): ...

4. Enum arguments: typer renders ApplicationStatus natively as a constrained choice — see status_cmd. Use this rather than a free string with manual validation.
5. File path arguments: use typer.Option(..., exists=True, dir_okay=False) to get free validation. See the add command's --resume for the pattern.
6. Update the README quickstart. New commands belong in the ## Quickstart block. Keep the example minimal — one realistic invocation.
7. Test the underlying core function in tests/test_core.py. CLI tests are intentionally light per the brief — there is no tests/test_cli.py today, and that's a deliberate choice. If you genuinely need argument-parsing coverage (e.g. a tricky flag combination), create tests/test_cli.py with typer's CliRunner; otherwise rely on core tests + manual smoke (uv run jobtrack verb --help).

Skeleton

@app.command("verb")
def verb_cmd(
    query: str = typer.Argument(..., help="ID or company"),
    flag: bool = typer.Option(False, "--flag", help="Describe."),
):
    """Imperative one-liner. (`jobtrack verb --help` shows this.)"""
    meta = _resolve_or_exit(query)
    try:
        result = core.do_the_thing(meta.id, flag=flag)
    except ValueError as e:
        console.print(f"[red]{e}[/red]")
        raise typer.Exit(2)
    console.print(f"[green]Done[/green] {result.id}")

If the command should also be exposed via MCP

Decide deliberately. The brief explicitly keeps add CLI-only because it needs files on disk at submit time. Most read-style commands belong in MCP too; most write-style commands do if they're things you'd do from a chat session. If yes, use the add-mcp-tool skill next.

Anti-patterns

• ❌ Calling storage.* directly from the CLI. Go through core.
• ❌ Catching core.AmbiguousQuery / core.NotFound inline — that's what _resolve_or_exit is for.
• ❌ Using print() instead of console.print(). Loses the rich formatting and the Windows UTF-8 setup at the top of cli.py was specifically done for the console object.
• ❌ Putting business logic tests in test_cli.py (if you create it). Business logic belongs in test_core.py; CLI tests are for argument parsing and exit codes only.

Verify

uv run pytest -v
uv run jobtrack verb --help     # confirm help text
uv run jobtrack verb <real-id>  # smoke test against the dev store