goodeye 0.7.0

Goodeye CLI: share and run outcome-aligned AI workflows from the terminal.

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+.

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

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

Quickstart

# 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 [e-mail]
goodeye register-verify --email [e-mail] --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

Workflow input

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

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:

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:

---
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:

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-4o", "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:

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:

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:

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:

goodeye login

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

goodeye register --email [e-mail]
goodeye register-verify --email [e-mail] --code 123456

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

goodeye login --email [e-mail]
goodeye login-verify --email [e-mail] --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

goodeye login
    Interactive sign-in for humans: browser/device-code flow; saves
    credentials on success.

goodeye login --email EMAIL
    Non-interactive email-code login start for agents and automation. Does not
    save credentials until you run goodeye login-verify with the emailed code.

goodeye login-verify --email EMAIL --code CODE
    Complete non-interactive email login and save credentials locally.

goodeye register --email EMAIL
    Start non-interactive account registration (emails a code when eligible).

goodeye register-verify --email EMAIL --code CODE
    Complete registration and save credentials locally.

goodeye logout
    Sign out on this machine by removing saved credentials. The key stays
    valid on the server; use `goodeye auth revoke-key` to disable it.

goodeye whoami
    Show who you're signed in as.

goodeye auth create-key --name NAME [--copy]
    Create a new API key. The secret is shown once - save it somewhere safe.

goodeye auth list-keys
    List your API keys. Secrets are never shown.

goodeye auth revoke-key <key-id-or-name>
    Revoke an API key. The key stops working immediately. The argument may
    be the ID shown by `auth list-keys` or a unique key name.

goodeye workflows list [--filter mine|shared-with-me|all] [--tag TAG] [--search QUERY] [--json]
    List workflows you can access (owned + shared with you via grants). The
    ID column is accepted by `get`, `delete`, and grant commands. When signed
    in, you can also use your own workflow name (slug).

goodeye workflows search <query> [--filter mine|shared-with-me|all] [--tag TAG] [--limit N] [--json]
    LLM-ranked natural-language search over workflows you can access.
    Use this when you remember roughly what a workflow does but not its
    name; use `list` for plain enumeration or tag filtering.

goodeye workflows get <id-or-name> [--version N] [--output PATH] [--json]
    Download a workflow. Prints markdown to stdout (wrapped with
    agent-facing markers); --json prints the full record. Authentication is
    required: workflows are private.

goodeye workflows publish <file.md|-> [--name NAME] [--description TEXT] [--outcome TEXT] [--tag TAG] [--expected-version-token TOKEN]
    Publish a workflow from markdown. Use `-` to read markdown from stdin,
    which is preferred for generated agent output. File input is still useful
    for durable local files. Always private. If a workflow with the same name
    already exists under your account, a new version is appended (pass
    --expected-version-token to confirm the parent version). Metadata may come
    from flags, front matter, or both; flags override front matter. `name`,
    `description`, and `outcome` are required. Repeat --tag to set tags. To
    share publicly, run `goodeye templates publish <workflow-uuid-or-name>` as
    a separate step.

goodeye workflows delete <id-or-name> [--yes]
    Delete a workflow you own.

goodeye workflows teach <id-or-name> [--trigger-context JSON]
    Fetch the teach SKILL pack for an existing workflow. The pack is
    printed to stdout for the calling agent to follow; persist the
    refined workflow with `goodeye workflows publish - --name <name> --description <description> --outcome <outcome> --source teach --expected-version-token <captured token>`.

goodeye workflows lineage <id-or-name> [--json]
    Show a workflow's fork lineage (parent template, upstream latest).

goodeye workflows grant <id-or-name> <grantee> <view|edit|admin>
    Share a workflow with a user email or @team handle.

goodeye workflows revoke-grant <id-or-name> <grantee>
    Revoke a direct grant.

goodeye workflows grants <id-or-name> [--json]
    List grants on a workflow.

goodeye workflows leave <id-or-name> [--yes]
    Remove your own direct grant on a shared workflow.

goodeye workflows transfer-ownership <id-or-name> <new-owner>
    Transfer a workflow you own to another user.

goodeye templates list [--filter all|mine] [--search QUERY] [--json]
    Browse the public template catalog. Anonymous reads allowed.

goodeye templates search <query> [--filter all|mine] [--limit N] [--json]
    LLM-ranked natural-language search over public templates.

goodeye templates get <identifier> [--version N] [--output PATH] [--json]
    Fetch a public template by UUID or @handle/slug[@vN]. Anonymous reads
    allowed; non-owner reads include an unverified-template safety banner.

goodeye templates publish <workflow-uuid-or-name> [--release-notes TEXT]
    Publish a private workflow as a new public template version.
    Requires a claimed handle.

goodeye templates unpublish <template-ref> <version>
    Soft-unpublish a single template version. Existing forks keep working.
    <template-ref> is a template UUID or @handle/slug.

goodeye templates fork <identifier> [--version N] [--name NAME]
    Fork a public template into a private workflow. Authentication required.

goodeye templates delete <template-ref> [--reason TEXT]
    Soft-delete a template you own. Existing forks keep working.
    <template-ref> is a template UUID or @handle/slug.

goodeye templates undelete <template-ref>
    Restore a previously deleted template you own.
    <template-ref> is a template UUID or @handle/slug.

goodeye templates deprecate-version <template-ref> <version> --message TEXT
    Flag a single template version as deprecated, with a message shown
    to anyone who forks that version.
    <template-ref> is a template UUID or @handle/slug.

goodeye templates transfer-ownership <template-ref> <user-id-or-email-or-handle>
    Hand a template off to another Goodeye user. Owner only.
    <template-ref> is a template UUID or @handle/slug.

goodeye templates run-verifier <template-ref> <verifier-name> [--input KEY=VALUE]... \
                               [--media-url URL] [--anonymous] [--json]
    Run a verifier published with a template version against ad-hoc input.
    Anonymous calls (`--anonymous`) skip credentials and are rate limited;
    authenticated calls use your saved credentials. --input is repeatable
    and must match the verifier's input contract; --media-url is required
    for text_image and image contracts.

goodeye verifiers deploy <config.json|->
    Deploy a verifier from JSON config (or append a new version). Use `-` to
    read verifier config JSON from stdin, which is preferred for generated
    agent output. File input is still useful for durable local config files.
    Required fields: name, description, criterion, input_contract. input_fields
    required for text and text_image contracts; few_shot_examples and
    model_settings optional. expected_version_token is required when
    re-deploying an existing verifier (get it from `verifiers list`).

goodeye verifiers list [--json]
    List active verifiers you own with their current version and version token.

goodeye verifiers show <verifier_id> [--version N] [--json]
    Show one verifier version: criterion, contract, calibration, config_hash.

goodeye verifiers run <verifier_id> [--inputs-json JSON] [--media-url URL] \
                                    [--version N] [--workflow-id UUID] \
                                    [--workflow-version N] [--workflow-ref TEXT] \
                                    [--run-id TEXT] [--json]
    Run a verifier and print PASS/FAIL plus reasoning. --inputs-json keys
    must match the version's input_fields exactly. --media-url is required
    for text_image and image contracts.

goodeye verifiers revoke <verifier_id> [--yes]
    Revoke a verifier you own. Irreversible; existing run rows are kept.

goodeye design
    Print the workflow-designer prompt to stdout. Pipe it into your AI
    assistant to start designing a workflow + verifier:
        goodeye design
    Only redirect to a file when you intentionally want a durable local prompt copy.

goodeye me claim-handle <handle>
    Claim a handle (your publish identity).

goodeye me rename-handle <new-handle>
    Change a previously claimed handle. Subject to a cooldown and yearly
    cap; old-handle template URLs redirect for a 90-day window.

Configuration

Credentials

• GOODEYE_API_KEY env var (highest precedence).
• ~/.config/goodeye/credentials.json (or $XDG_CONFIG_HOME/goodeye/).

Credential files are created with mode 0600.

Server

• GOODEYE_SERVER env var.
• server field inside credentials.json.
• Default: https://api.goodeyelabs.com.

REST API, not the CLI

This CLI is pinned to the /v1/ REST API contract. If you are integrating programmatically and want a stable contract, prefer the REST API directly; the CLI is a convenience layer over it.

Contributing

See CONTRIBUTING.md for local-dev setup and the PR process. Issues and PRs welcome.

License

MIT. See LICENSE.