Goodeye

PyPI version Python versions License

Goodeye makes an AI agent meet your standard before you ever see the output, even on work too subjective for a test.

goodeye is the command-line surface for Goodeye. The same capability reaches your agent over an MCP server and a REST API too, so it works wherever your agent runs. This CLI talks to the public /v1 REST API.

How it works

You capture the work that moves an outcome as a markdown runbook, called a workflow, and pair it with checks, called verifiers, that score an agent's output against the standard you set. The agent runs the workflow, the verifiers judge the result, and the agent revises until the output clears your bar. Workflows stay private to you until you choose to share one publicly as a template.

A verifier can be deterministic (format, schema, tests, numeric bounds) or an LLM judge for the calls no test can make, like tone or image quality. The full picture is at https://goodeye.dev/docs/overview.

Your AI agent is the primary caller

The CLI is built to be driven by an AI coding agent on your behalf, though every command also works when you run it yourself. The intended loop: you ask your agent to run a Goodeye workflow, it fetches the body with goodeye workflows get <name> (or goodeye templates get @handle/slug), and it executes those instructions as your runbook instead of printing or summarizing them. The get commands wrap the body in agent-facing markers so the calling agent knows to run it. Pass --output PATH or --json when you want the raw content instead.

Install

Requires Python 3.12 or later.

uv tool install goodeye
# or: pipx install goodeye
# or: pip install goodeye

The goodeye command is then on your PATH. Run goodeye update to upgrade to the latest release, or goodeye update --check to see whether one is available.

Quickstart

Run a public template, no account needed

Browsing, fetching, and running public templates need no sign-in.

goodeye templates list
goodeye templates get @randalolson/high-signal-chart-workflow

templates get prints the workflow body, and your agent follows it: it finds a dataset, renders a chart, and runs the template's pinned verifier, revising until the chart passes. That verifier run is the step your agent makes, drawing on a small per-network credit grant:

# what your agent runs against the finished chart:
goodeye verifiers run 89dcc843-d056-44d9-ae34-ebcff4903885 \
  --version 1 --media-url '<public-https-chart-url>' --anonymous

Author your own workflow

goodeye login                          # or: goodeye register --email [email protected]
goodeye me claim-handle your-handle    # one time, required before you publish a template

goodeye design                         # prints the designer prompt; pipe it to your agent to draft a workflow and its verifiers

# save the draft from your agent's output (stdin keeps a stray file out of the working directory):
goodeye workflows publish - \
  --name my-workflow \
  --description "One sentence on what this does and when to use it." \
  --outcome "The result this workflow moves" <<'EOF'
# Body

The workflow body your agent will execute.
EOF

goodeye workflows get my-workflow      # fetch it back for an agent to run
goodeye templates publish my-workflow  # share it publicly as a template

What the CLI can do

These command areas cover the whole surface. Run goodeye --help or goodeye <area> --help for the exact commands and flags, and see the full reference at https://goodeye.dev/docs/cli.

Area	What it does	Docs
workflows	Find, save, version, run, share, and improve your private workflows, including teach, optimize, audit, and local file sync	https://goodeye.dev/docs/workflows
templates	Browse the public catalog, publish a workflow as a template, and fork one to customize	https://goodeye.dev/docs/templates
verifiers	Deploy and run the LLM-judge checks a workflow calls to grade agent output	https://goodeye.dev/docs/verifiers
image-generators	Deploy reusable image generators and generate images a workflow can call	https://goodeye.dev/docs/image-generators
images	Upload and manage hosted images with stable URLs	https://goodeye.dev/docs/images
teams	Create teams and manage membership so a workflow can be shared with a group	https://goodeye.dev/docs/teams
referrals	View your referral code and redeem someone else's	https://goodeye.dev/docs/referrals
invitations	Accept, decline, or cancel team and ownership-transfer invitations	https://goodeye.dev/docs/cli
billing	Upgrade to or cancel Pro (plan upgrade / plan cancel), open the billing portal, buy a one-time credit top-up, or manage automatic top-ups (auto-topup show / set / off)	https://goodeye.dev/docs/cli
auth, me, usage	Manage API keys, claim your handle, and check credit usage	https://goodeye.dev/docs/cli
design	Print the workflow-designer prompt for your agent	https://goodeye.dev/docs/cli

Session commands sit at the top level: login, register, logout, whoami, and update.

Authentication and configuration

Sign in interactively with goodeye login or goodeye register. Both open a browser device-code flow and save your credentials on success. For agents and automation without a browser, use the email-code flow:

goodeye register --email [email protected]
goodeye register-verify --email [email protected] --code 123456
# existing account: goodeye login, then goodeye login-verify

goodeye whoami shows who you are, and goodeye logout removes the local credentials. Agents and scripts can authenticate with an API key instead: create one with goodeye auth create-key --name my-agent and pass it as the GOODEYE_API_KEY environment variable.

The CLI reads credentials from GOODEYE_API_KEY first, then from ~/.config/goodeye/credentials.json (written with 0600 permissions). It targets https://api.goodeye.dev by default; override that with GOODEYE_SERVER. Full authentication details are at https://goodeye.dev/docs/cli.

CLI, MCP, or REST

The CLI is a convenience layer over the public /v1 REST API. For a stable programmatic contract, call that REST API directly (https://goodeye.dev/docs/rest-api). To drive Goodeye from an MCP client, connect to mcp.goodeye.dev/mcp (https://goodeye.dev/docs/mcp). Your workflows and their verifiers reach your agent on every surface.

Documentation

• Overview and mental model: https://goodeye.dev/docs/overview
• Getting started: https://goodeye.dev/docs/getting-started
• CLI reference, every command and flag: https://goodeye.dev/docs/cli
• Workflows: https://goodeye.dev/docs/workflows
• Verifiers: https://goodeye.dev/docs/verifiers
• Templates: https://goodeye.dev/docs/templates
• Public template catalog: https://goodeye.dev

Contributing

See CONTRIBUTING.md for local dev setup and the pull-request process. Issues and pull requests are welcome.

License

MIT. See LICENSE.