Metadata-Version: 2.4
Name: goodeye
Version: 0.7.1
Summary: Goodeye CLI: share and run outcome-aligned AI workflows from the terminal.
Project-URL: Repository, https://github.com/Goodeye-Labs/goodeye-cli
Project-URL: Issues, https://github.com/Goodeye-Labs/goodeye-cli/issues
Author: Goodeye Labs
License: MIT License
        
        Copyright (c) 2026 Goodeye Labs
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: agents,ai,cli,goodeye,llm,mcp,workflows
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development
Classifier: Topic :: Utilities
Requires-Python: >=3.12
Requires-Dist: httpx>=0.27
Requires-Dist: pydantic-settings>=2.4
Requires-Dist: pydantic>=2.7
Requires-Dist: pyyaml>=6
Requires-Dist: rich>=13
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

# 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`.

## 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
```

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

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

```
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](./CONTRIBUTING.md) for local-dev setup and the PR
process. Issues and PRs welcome.

## License

MIT. See [LICENSE](./LICENSE).
