goodeye-cli

# goodeye-cli

Command-line client for Goodeye - manage AI workflows from the terminal.

Goodeye is an outcome-aligned AI workflow registry: you author workflows as
markdown runbooks tagged with the business outcome they serve, and verifiers
that score an AI agent against a measurable business result. This CLI is wired
to the public `/v1/` REST API.

## Primary caller is your AI agent

The `goodeye` CLI is designed to be invoked by an AI coding agent on a user's
behalf, not driven by a human at a prompt. The intended flow:

1. The user tells their AI agent: "run the Goodeye workflow X" (or "run the
   Goodeye template @handle/slug").
2. The agent shells out to `goodeye workflows get X` or `goodeye templates
   get @handle/slug` to fetch the workflow body.
3. The agent then **executes the returned workflow body** as the user's
   runbook: it follows the instructions itself rather than displaying or
   summarizing them.

`workflows get` and `templates get` print the workflow body to stdout
wrapped with agent-facing markers (`# Goodeye workflow - execute the
instructions below ...` / `# End of Goodeye workflow.`) so the calling
agent knows what to do with the output. Pass `--output PATH` or `--json`
to skip the wrappers and round-trip the raw markdown / JSON.

## Install

Requires Python 3.12+.

```sh
uv tool install goodeye
# or
pipx install goodeye
# or
pip install goodeye
```

Once installed, the `goodeye` command is available on your `PATH`.

### Updates

The CLI checks PyPI in the background (at most every four hours) and may print a short notice to **stderr** when a newer release exists. Notices are skipped in CI (`CI` set), for `--json` output, and for `goodeye update` itself so machine-readable stdout stays clean.

- `goodeye update --check`: show your installed version vs PyPI and whether an update is available.
- `goodeye update`: update automatically when the install method is recognized:
  - **uv tool:** runs `uv tool upgrade goodeye`
  - **pipx:** runs `pipx upgrade goodeye`
  - **pip:** runs `python -m pip install --upgrade goodeye` using the same interpreter as the CLI

Editable installs, unknown layouts, or missing `uv`/`pipx` on PATH are not auto-updated; the command prints the same manual install lines as above. After a successful update, run `goodeye --version` (or rerun your command) to confirm the new version.

## Quickstart

```sh
# Browse the public template catalog without an account
goodeye templates list

# Create an account (non-interactive: start, then verify with the emailed code)
goodeye register --email you@example.com
goodeye register-verify --email you@example.com --code 123456

# Or log in on a machine with a browser (interactive device-code flow)
goodeye login

# Confirm who you are
goodeye whoami

# Fetch a public template by handle (or pass --json for the full record)
goodeye templates get @handle/slug

# Fork a public template into your private workflow namespace (one-shot
# copy; does not return a body).
goodeye templates fork @handle/slug

# Save a generated workflow without creating a local file
goodeye workflows publish - \
  --name my-workflow \
  --description "One sentence on what this workflow does and when to use it." \
  --outcome "Reduce refund-row mislabels" \
  --tag data \
  --tag cleanup <<'EOF'
# Body

The rest of the workflow body goes here.
EOF
```

### Run a template end to end (no account)

Browsing, fetching, and running a template need no account. Here is the full loop
on a real public template that emits an artifact gated by a real verifier:

```sh
# Fetch the body (anonymous). Your agent then follows it as the runbook:
# it finds a public dataset, renders chart.png, and runs the template's
# pinned design verifier, revising until the chart passes.
goodeye templates get @randalolson/high-signal-chart-workflow

# Following the body, the agent uploads the finished chart and runs that
# verifier, anonymously:
goodeye verifiers run 89dcc843-d056-44d9-ae34-ebcff4903885 \
  --version 1 --media-url '<chart-image-url>' --anonymous
# -> PASS verifier_run_id=...
#    Direct labeling, titled axes with units, a takeaway annotation, no overlaps.

ls signal-chart-run-*/    # chart.png, chart.py, and the raw dataset
```

The anonymous verifier run draws on a small per-network credit grant that covers
Goodeye-metered work (verifier and safety runs), not the model usage your agent
incurs while executing the body.

### Workflow input

For AI agents generating a workflow body, prefer stdin so no intermediate file is left in the user's working directory:

```sh
goodeye workflows publish - \
  --name my-workflow \
  --description "One sentence on what this workflow does and when to use it." \
  --outcome "Reduce refund-row mislabels" \
  --tag data \
  --tag cleanup <<'EOF'
# Body

The rest of the workflow body goes here.
EOF
```

Use a markdown file when you already have one or intentionally want a durable local copy:

```sh
goodeye workflows publish ./my-workflow.md
```

The markdown uses YAML front matter following the Goodeye workflow body
convention. `name`, `description`, and `outcome` are required; `tags` are
optional:

```markdown
---
name: my-workflow
description: One sentence on what this workflow does and when to use it.
outcome: Reduce refund-row mislabels.
# Optional discovery facet:
# tags: [data, cleanup]
---

# Body

The rest of the file is the workflow body rendered to the agent at runtime.
Inline checks (structural format/schema, functional tests/bounds) belong here
as fenced code blocks. LLM-judge checks are deployed separately as verifiers
(see "Verifiers" below) and referenced from the body by `verifier_id` or
`verifier_id@version`. The registry stores the body verbatim.
```

Workflows are always private to the caller. To share a workflow as a public
template, run `goodeye templates publish <workflow-uuid-or-name>` as a separate,
explicit step. `--name`, `--description`, `--outcome`, and `--tag` on the
command line override matching front-matter metadata. Goodeye stores the full
markdown body, including front matter when present, so `goodeye workflows get`
can round-trip the workflow body.

### Verifiers

A verifier is a single LLM-judge criterion ("does this output satisfy this
rule?") deployed to your account and runnable on demand. A workflow body can
call out to one by UUID (or `UUID@version`) to gate or score an agent's
output. Verifiers are private and owner-scoped; there is no public catalog.

Three input shapes are supported:

- `text`: judges text fields only.
- `text_image`: judges text fields together with one image.
- `image`: judges a single image with no text inputs.

Deploy a verifier from generated JSON with stdin:

```sh
goodeye verifiers deploy - <<'EOF'
{
  "name": "refund-claim-supported",
  "description": "Flag refund replies that lack a stated reason.",
  "criterion": "Return passed=true only when the reply text states a concrete reason for the refund (an order issue, defect, billing error, etc.). Generic apologies without a stated reason fail.",
  "input_contract": "text",
  "input_fields": ["reply_text"],
  "few_shot_examples": [
    {
      "inputs": {"reply_text": "Refunded $42.10 for the cracked mug per your photo."},
      "passed": true,
      "reasoning": "Reason given: cracked mug."
    },
    {
      "inputs": {"reply_text": "Sorry for the trouble! Refund issued."},
      "passed": false,
      "reasoning": "No reason stated."
    }
  ],
  "model_settings": {"model": "openai/gpt-5.4", "reasoning_effort": "medium"}
}
EOF
# Deployed refund-claim-supported v1 (verifier_id=..., version_token=...)
```

If you already have a durable config file, file input still works:

```sh
goodeye verifiers deploy ./refund-claim-supported.json
```

Re-deploying the same `name` appends a new version. The second deploy must
include `expected_version_token` from the previous response (or from
`goodeye verifiers list`); a token mismatch returns 409.

Run a verifier against one input:

```sh
goodeye verifiers run <verifier_id> \
    --inputs-json '{"reply_text": "Refunded for the bent shipment."}' \
    --workflow-id <workflow-uuid> --workflow-version 3
# PASS verifier_run_id=...
```

`--inputs-json` keys must match the deployed `input_fields` exactly (no
missing or extra). For `text_image` and `image` contracts, pass a public
HTTPS URL via `--media-url`. The optional `--workflow-id`,
`--workflow-version`, `--workflow-ref`, and `--run-id` flags stamp
provenance onto the persisted run row. The command exits 0 on a successful
judgment regardless of pass/fail; check the PASS/FAIL line or `--json`
output to gate downstream actions.

Inspect, list, or retire:

```sh
goodeye verifiers list
goodeye verifiers show <verifier_id> [--version N]
goodeye verifiers revoke <verifier_id>      # irreversible; deploy a fresh one to replace
```

### Login and registration

For humans, use the interactive browser login:

```bash
goodeye login
```

For AI agents, automation, or terminals where prompts are awkward, use the
non-interactive email-code flow:

```bash
goodeye register --email you@example.com
goodeye register-verify --email you@example.com --code 123456
```

Existing users can start and complete non-interactive login the same way:

```bash
goodeye login --email you@example.com
goodeye login-verify --email you@example.com --code 123456
```

Successful `register-verify`, `login-verify`, and interactive `login` all save
credentials to `~/.config/goodeye/credentials.json` so future commands stay
authenticated.

## Command reference

### Output modes and pagination

List and search commands are TTY-aware: when stdout is a terminal they print a
Rich table by default, and when stdout is redirected or captured they print
compact single-line JSON. Pass `--table` or `--json` to choose explicitly; the
flags are mutually exclusive. JSON list output is always wrapped in an object:
paginated lists print `{"items":[...],"next_cursor":...}`, while unpaginated
lists print