===============
LIBRARY RULES
===============
From library maintainers:
- Goodeye stores workflows (private to the owner) and shares them publicly as templates.
- An agent fetches a workflow or template body and executes it as a runbook, it does not summarize it.
- Authenticate MCP with OAuth or a good_live_ API key. Authenticate REST with a good_live_ API key. Anonymous callers can browse public templates over REST.
- The MCP endpoint is mcp.goodeye.dev/mcp. The REST base is api.goodeye.dev/v1.
- Verifiers must be outcome-specific, never a holistic is-this-good check.

### Get a Template CLI Example

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/templates.md

Use this command to retrieve a specific template by its identifier. Options include specifying a version, output file, and requesting JSON output.

```bash
goodeye templates get <identifier> --version <version> --output <file> --json
```

--------------------------------

### Get Template MCP Tool Example

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/templates.md

Use the 'get_template' command from the MCP tool to retrieve a template.

```bash
get_template
```

--------------------------------

### Get a Specific File CLI Example

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/templates.md

Use this command to download the raw bytes of a single published file from a template. You can optionally specify a SHA256 hash to verify the downloaded content.

```bash
goodeye templates get-file <identifier> <path> --output <file> --sha256 <HASH>
```

--------------------------------

### Example Referral Status Output

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/referrals.md

This is an example of the output you might receive when checking your referral status. It includes your code, instructions for new users, and your referral statistics.

```text
Your referral code: K7MNP2QR

Instructions:
  Share this code and ask the new user to install the Goodeye CLI, then run
  `goodeye login --referral-code K7MNP2QR` to sign in and claim their bonus
  credits. If they use Goodeye through an MCP client, they can connect their
  account and redeem the code with the redeem referral tool.

Redeemed: 8
Activated: 3
Credits earned: $15.00
Slots remaining: 2
```

--------------------------------

### Example Usage Output

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/accounts-and-billing.md

Example output from the 'goodeye usage' command, showing tier, available credits, and refill schedule. Amounts are dynamic and may change.

```text
Tier: hobby
Available: $3.21
  refills to $5.00 on 07/01/2026
```

--------------------------------

### Start a Guided Workflow Design Session

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/getting-started.md

Initiate an interactive design session to create a new workflow and its verifiers. The session guides you through the process and saves the result.

```sh
goodeye design
```

--------------------------------

### Teach Workflow

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/rest-api.md

Provide new examples to an existing workflow to enhance its learning.

```http
POST /v1/workflows/{id_or_slug}/teach
```

--------------------------------

### Teach Workflow

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/rest-api.md

Teaches an existing workflow with new examples.

```APIDOC
## POST /v1/workflows/{id_or_slug}/teach

### Description
Teaches an existing workflow by providing new examples.

### Method
POST

### Endpoint
/v1/workflows/{id_or_slug}/teach

### Parameters
#### Path Parameters
- **id_or_slug** (string) - Required - The ID or slug of the workflow to teach.
```

--------------------------------

### Install Goodeye CLI

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/getting-started.md

Install the Goodeye CLI using pipx or pip. Ensure Python 3.12 or newer is installed.

```sh
uv tool install goodeye
```

```sh
pipx install goodeye
```

```sh
pip install goodeye
```

--------------------------------

### Search Templates MCP Tool Example

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/templates.md

Use the 'search_templates' command from the MCP tool to search for templates.

```bash
search_templates
```

--------------------------------

### Search Templates CLI Example

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/templates.md

Use this command for natural-language search over the public catalog. Specify your query and optionally filter results and set a limit.

```bash
goodeye templates search "<query>" --filter <filter> --limit <limit>
```

--------------------------------

### Install Goodeye CLI

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/cli.md

Installs the Goodeye CLI using uv, pipx, or pip. Requires Python 3.12 or later.

```sh
uv tool install goodeye
```

```sh
# or: pipx install goodeye
```

```sh
# or: pip install goodeye
```

--------------------------------

### List Templates CLI Example

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/templates.md

Use this command to list available templates. You can filter by 'all' or 'mine', perform a search, set a limit, include archived templates, and retrieve all results.

```bash
goodeye templates list --filter all|mine --search <query> --limit <limit> --all --include-archived
```

--------------------------------

### List Templates MCP Tool Example

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/templates.md

Use the 'list_templates' command from the MCP tool. The 'include_archived' parameter can be set.

```bash
list_templates(include_archived=true)
```

--------------------------------

### Verify Goodeye CLI Installation

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/getting-started.md

Confirm that the Goodeye CLI has been installed correctly by checking its version.

```sh
goodeye --version
```

--------------------------------

### Workflow Creation Response

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/rest-api.md

Example response upon successful creation or update of a workflow.

```json
{
  "workflow_id": "89dcc843-d056-44d9-ae34-ebcff4903885",
  "version": 1,
  "version_token": "...",
  "name": "Weekly report",
  "slug": "weekly-report",
  "verifiers": []
}
```

--------------------------------

### Design Workflow via CLI

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/workflows.md

Use the `goodeye design` command in the CLI to start a guided design session for a workflow. You can pipe the output into a file.

```bash
goodeye design > prompt.md
```

--------------------------------

### Get Template File

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/cli.md

Writes an attached file from a template to a local path as raw bytes. Use `--sha256` to content-address the fetch.

```sh
goodeye templates get-file <identifier> <path> --output PATH [--sha256 HASH]
```

--------------------------------

### Generate Image using REST API

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/image-generators.md

This example shows how to make a POST request to the REST API to generate an image using a system tier. It includes the prompt and the number of images requested.

```http
POST /v1/image-generators/system:image-standard/runs
Content-Type: application/json
Authorization: Bearer good_live_EXAMPLE_xxxxxxxx

{"prompt": "A product hero shot, soft studio lighting", "num_images": 1}
```

--------------------------------

### Get Workflow Designer Prompt

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/rest-api.md

Retrieves the workflow designer prompt pack. Authentication is required.

```shell
GET /v1/design/workflow-prompt
```

--------------------------------

### Add Goodeye MCP Server with API Key (Claude CLI)

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/mcp.md

Adds the Goodeye MCP server using the Claude CLI with an API key for authentication. Replace the example key with your actual key.

```sh
claude mcp add --transport http goodeye \
  https://mcp.goodeye.dev/mcp \
  --header "Authorization: Bearer good_live_EXAMPLE_xxxxxxxx"
```

--------------------------------

### Get Workflow Details

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/cli.md

Fetches the workflow body. By default, prints markdown to stdout wrapped in agent-facing markers. Use `--json` to print the full record as JSON or `--output PATH` to save the body to a file without markers. Authentication is required as workflows are private.

```sh
goodeye workflows get <id-or-name> [--version N] [--output PATH] [--json]
```

--------------------------------

### GET /v1/i/{token}.{ext}

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/rest-api.md

Serves the raw bytes of a private image using a secure token. Supports HEAD requests for metadata. The extension in the URL is cosmetic.

```APIDOC
## GET /v1/i/{token}.{ext}

### Description
Public byte-serve (also HEAD) for raw image bytes by token.

### Method
GET

### Endpoint
/v1/i/{token}.{ext}

### Parameters
#### Path Parameters
- **token** (string) - Required - The secure token identifying the image.
- **ext** (string) - Required - The cosmetic file extension (e.g., 'png', 'jpg').
```

--------------------------------

### API Key Creation Response

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/rest-api.md

Example JSON response upon successful API key creation. Includes the key's ID, name, and the secret key itself. The secret key is only provided once.

```json
{
  "id": "key_...",
  "name": "my-automation",
  "key": "good_live_..."
}
```

--------------------------------

### Show Verifier Details

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/cli.md

Displays details of a specific verifier version, including its criterion, input contract, and calibration examples. This command is owner-only.

```sh
goodeye verifiers show <verifier_id> [--version N] [--json]
```

--------------------------------

### User Profile Response

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/rest-api.md

Example JSON response when retrieving authenticated user information. Contains user ID, email, handle, and handle claim timestamp.

```json
{
  "id": "9f8c1e2a-3b4d-4c5e-8f6a-1b2c3d4e5f60",
  "email": "you@example.com",
  "handle": "yourhandle",
  "handle_claimed_at": "2024-06-01T12:00:00Z"
}
```

--------------------------------

### Get Template REST API Example

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/templates.md

This REST API endpoint retrieves a specific template by its identifier.

```http
GET /v1/templates/{identifier}
```

--------------------------------

### Goodeye Images CLI Commands

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/cli.md

Provides a comprehensive list of commands for managing hosted images, including upload, list, get, update, and delete operations. Supports visibility and TTL settings.

```sh
goodeye images upload <file> [--visibility public|private] [--ttl SECONDS] [--json]
```

```sh
goodeye images list [--source upload|generated] [--visibility public|private] \
  [--limit N] [--cursor TOKEN] [--all] [--json|--table]
```

```sh
goodeye images get <image-id> [--json]
```

```sh
goodeye images update <image-id> [--visibility public|private] \
  [--ttl SECONDS|--permanent] [--rotate-view-secret] [--json]
```

```sh
goodeye images delete <image-id> [--yes]
```

--------------------------------

### Show Verifier

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/verifiers.md

Returns one verifier version in full: criterion, input contract, input fields, calibration examples, and judge config. Defaults to the current version; pin one with `--version`.

```APIDOC
## GET /v1/verifiers/{verifier_id}

### Description
Returns one verifier version in full: criterion, input contract, input fields, calibration examples, and judge config. Defaults to the current version; pin one with `--version`.

### Method
GET

### Endpoint
/v1/verifiers/{verifier_id}

### Parameters
#### Path Parameters
- **verifier_id** (string) - Required - The ID or name of the verifier.

#### Query Parameters
- **version** (integer) - Optional - Pin a specific version of the verifier.
```

--------------------------------

### Get Template File REST API Example

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/templates.md

This REST API endpoint retrieves a specific file from a template. You can specify the path to the file.

```http
GET /v1/templates/{identifier}/files?path=
```

--------------------------------

### Interactive Sign-in and Registration

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/cli.md

Use 'register' to create a new account and 'login' to sign in to an existing one. Both commands initiate a device-code browser flow and save credentials locally upon success.

```sh
goodeye register   # create a new account
goodeye login      # sign in to an existing account
```

--------------------------------

### Print Workflow Designer Prompt

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/cli.md

Use this command to print the workflow designer prompt to standard output. This prompt is the recommended starting point for designing new workflows. Sign-in is required for this command to function.

```sh
goodeye design          # print the workflow-designer prompt to stdout
```

--------------------------------

### GET /v1/verifiers/{verifier_id}

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/rest-api.md

Fetches detailed information about a specific verifier, including its criterion, calibration examples, and contract. You can specify a version using the `version` query parameter. Accepts either a verifier's UUID or its user-scope name.

```APIDOC
## GET /v1/verifiers/{verifier_id}

### Description
Get a verifier version including criterion, calibration examples, and contract. Pass `?version=N` to pin. Accepts UUID or accessible user-scope verifier name.

### Method
GET

### Endpoint
/v1/verifiers/{verifier_id}

### Parameters
#### Path Parameters
- **verifier_id** (string) - Required - The ID or name of the verifier.

#### Query Parameters
- **version** (integer) - Optional - Specify a version number to retrieve a specific version of the verifier.
```

--------------------------------

### Publish an existing skill as a workflow

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/workflows.md

Use the 'publish' command to import a skill from disk into Goodeye as a workflow. You must supply an 'outcome' for discoverability. The SKILL.md file becomes the workflow body, and other files are uploaded alongside it.

```sh
goodeye workflows publish ~/.claude/skills/high-signal-chart \
  --outcome "Engagement on the charts we publish."
```

--------------------------------

### Get Public Template

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/cli.md

Fetches a public template by its identifier (UUID, @handle/slug, or @handle/slug@vN). Output format and flags are identical to `workflows get`.

```sh
goodeye templates get <identifier> [--version N] [--output PATH] [--json]
```

--------------------------------

### Add Demo Content to Template Page

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/templates.md

This markdown snippet demonstrates how to structure a demo README file for a template. It includes a title, descriptive text, an image reference, and an optional video link. Ensure images are referenced relatively within the 'demo/' directory and videos are from supported platforms for embedding.

```markdown
# What this produces

A publication-quality chart in minutes.

![Sample output](output.png)

https://www.youtube.com/watch?v=EXAMPLE
```

--------------------------------

### Fetch Workflow Teach Pack

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/cli.md

Retrieves the teach pack for a workflow, useful for interactive refinement. The output can be used with `workflows publish --source teach` to persist changes.

```sh
goodeye workflows teach <id-or-name>
```

--------------------------------

### Publish Workflow from Directory via CLI

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/workflows.md

Publish a workflow by providing a directory containing the `SKILL.md` file and any associated assets. This enables multi-file bundles.

```sh
goodeye workflows publish ./high-signal-chart
```

--------------------------------

### Get a workflow by ID or name

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/workflows.md

Fetch a workflow using its UUID or slug. By default, this returns the markdown body. Use the --json flag to get the full record, including metadata like file manifest and safety verification status.

```sh
goodeye workflows get <id-or-name>
```

--------------------------------

### GET /v1/templates

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/rest-api.md

Lists public templates. Supports filtering, searching, and pagination.

```APIDOC
## GET /v1/templates

### Description
List public templates. Supports filtering, searching, and pagination.

### Method
GET

### Endpoint
/v1/templates

### Parameters
#### Query Parameters
- **filter** (string) - Optional - Filters the templates. Possible values: `all`, `mine`.
- **search** (string) - Optional - Search query string.
- **limit** (integer) - Optional - Maximum number of results to return.
- **cursor** (string) - Optional - Pagination cursor for fetching the next page.
- **include_archived** (boolean) - Optional - Include archived templates (only for authenticated users when filtering by `mine`).
```

--------------------------------

### Accept Invitation via CLI

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/templates.md

Accept a template ownership invitation using the CLI. This command completes the ownership transfer process.

```bash
goodeye invitations accept <id>
```

--------------------------------

### GET /v1/api-keys

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/rest-api.md

Lists the metadata for all of the authenticated user's API keys.

```APIDOC
## GET /v1/api-keys

### Description
List your keys (metadata only, no secrets).

### Method
GET

### Endpoint
/v1/api-keys
```

--------------------------------

### Show a Verifier (CLI)

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/verifiers.md

Retrieves full details of a specific verifier version. Use --version to pin a particular version.

```sh
goodeye verifiers show <id-or-name> [--version N]
```

--------------------------------

### Publish a template version using CLI

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/templates.md

Use the CLI to publish a new version of a workflow as a template. The `--release-notes` flag allows you to add descriptive notes for the new version.

```sh
goodeye templates publish high-signal-chart \
  --release-notes "Tighten the takeaway annotation."
```

--------------------------------

### GET /v1/images/{image_id}

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/rest-api.md

Fetches the record for a specific image, identified by its unique ID.

```APIDOC
## GET /v1/images/{image_id}

### Description
Fetch one image record.

### Method
GET

### Endpoint
/v1/images/{image_id}

### Parameters
#### Path Parameters
- **image_id** (string) - Required - The ID of the image to fetch.
```

--------------------------------

### Create a Team using CLI

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/teams.md

Use this command to create a new team with a specified handle. The handle must be unique and adhere to specific formatting rules.

```bash
goodeye teams create my-team
```

--------------------------------

### Run a Platform-Managed System Verifier

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/verifiers.md

Invoke a platform-managed verifier using its system alias. Ensure you provide the expected inputs in JSON format.

```sh
goodeye verifiers run system:workflow-design-qa \
  --inputs-json '{"...": "..."}'
```

--------------------------------

### GET /v1/images

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/rest-api.md

Lists all images uploaded by the user. Supports filtering by source and visibility, and pagination.

```APIDOC
## GET /v1/images

### Description
List your images.

### Method
GET

### Endpoint
/v1/images

### Query Parameters
- **source** (string) - Optional - Filter images by their source.
- **visibility** (string) - Optional - Filter images by their visibility.
- **limit** (integer) - Optional - The maximum number of images to return.
- **cursor** (string) - Optional - A cursor for fetching the next page of results.
```

--------------------------------

### GET /v1/image-generators/{generator_id}

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/rest-api.md

Retrieves details for a specific image generator, identified by its unique ID.

```APIDOC
## GET /v1/image-generators/{generator_id}

### Description
Get an image generator version.

### Method
GET

### Endpoint
/v1/image-generators/{generator_id}

### Parameters
#### Path Parameters
- **generator_id** (string) - Required - The ID of the image generator to retrieve.
```

--------------------------------

### GET /v1/me/usage

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/rest-api.md

Retrieves the authenticated user's current billing period usage statistics.

```APIDOC
## GET /v1/me/usage

### Description
Returns your current billing period usage: tier, period dates, granted/used/remaining credits, and unpaid balance.

### Method
GET

### Endpoint
/v1/me/usage

### Request Example
```http
GET /v1/me/usage
Authorization: Bearer good_live_EXAMPLE_xxxxxxxx
```

See [Accounts and billing](accounts-and-billing.md) for tier details.
```

--------------------------------

### Buy Extra Credits via CLI

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/accounts-and-billing.md

Use this command to purchase additional credits via the command-line interface. Specify the amount in whole US dollars (5 to 500).

```bash
goodeye billing buy-credits --amount N
```

--------------------------------

### GET /v1/me

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/rest-api.md

Retrieves the authenticated user's account details, including ID, email, and handle.

```APIDOC
## GET /v1/me

### Description
Returns the authenticated caller's account id, email, and handle.

### Method
GET

### Endpoint
/v1/me

### Request Example
```http
GET /v1/me
Authorization: Bearer good_live_EXAMPLE_xxxxxxxx
```

### Response
#### Success Response (200)
- **id** (string) - The unique identifier for the account.
- **email** (string) - The email address associated with the account.
- **handle** (string) - The user's handle.
- **handle_claimed_at** (string) - The timestamp when the handle was claimed.

#### Response Example
```json
{
  "id": "9f8c1e2a-3b4d-4c5e-8f6a-1b2c3d4e5f60",
  "email": "you@example.com",
  "handle": "yourhandle",
  "handle_claimed_at": "2024-06-01T12:00:00Z"
}
```
```

--------------------------------

### Register and Login with Goodeye CLI

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/getting-started.md

Use these commands to create a new account or sign in to an existing one. This process opens a verification URL in your browser.

```sh
goodeye register   # new account
goodeye login      # existing account
```

--------------------------------

### Create a Team using MCP tool

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/teams.md

Use the `create_team` command within the MCP tool to create a new team.

```text
create_team
```

--------------------------------

### Get Public Template Catalog

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/rest-api.md

Retrieves a list of all available public templates. This endpoint does not require authentication.

```APIDOC
## GET /v1/templates

### Description
Retrieves a list of all public templates. Anonymous access is permitted.

### Method
GET

### Endpoint
/v1/templates
```

--------------------------------

### Search Templates REST API Example

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/templates.md

This REST API endpoint performs a search over the template catalog.

```http
POST /v1/templates/search
```

--------------------------------

### Deploy Verifier (Create or New Version)

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/rest-api.md

Use this endpoint to deploy a semantic verifier. Required fields include name, description, criterion, and input_contract. Input_fields is mandatory for text and text_image contracts. Few_shot_examples and model_settings are optional.

```http
POST /v1/verifiers
Authorization: Bearer good_live_EXAMPLE_xxxxxxxx
Content-Type: application/json

{
  "name": "response-clarity",
  "description": "Scores whether an answer is clear, direct, and free of hedging.",
  "criterion": "Return passed=true when the response is clear, direct, and free of unnecessary qualifiers.",
  "input_contract": "text",
  "input_fields": ["user_query", "agent_response"],
  "few_shot_examples": [
    {
      "inputs": {"user_query": "What is 2+2?", "agent_response": "4"},
      "passed": true,
      "reasoning": "Direct and complete."
    }
  ]
}
```

```json
{
  "verifier_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d",
  "name": "response-clarity",
  "version": 1,
  "version_token": "...",
  "status": "active"
}
```

--------------------------------

### Template Execution Result

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/getting-started.md

Example of a successful verification result for a chart, indicating it meets quality standards.

```text
PASS  Direct labeling, titled axes with units, and a takeaway annotation, with
no overlapping elements; the reader reaches the intended comparison on first view.
```

--------------------------------

### Get Specific Public Template

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/rest-api.md

Retrieves details for a specific public template by its identifier. This endpoint does not require authentication.

```APIDOC
## GET /v1/templates/{identifier}

### Description
Retrieves details for a specific public template using its unique identifier. Anonymous access is permitted.

### Method
GET

### Endpoint
/v1/templates/{identifier}

#### Path Parameters
- **identifier** (string) - Required - The unique identifier of the template.
```

--------------------------------

### Run a Verifier with JSON Inputs

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/verifiers.md

Execute a verifier with provided JSON inputs. Ensure the input keys match the verifier's input fields.

```sh
goodeye verifiers run claims-cite-source \
  --inputs-json '{"response": "...", "source": "..."}'
```

--------------------------------

### Cursor MCP Server Configuration (Basic)

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/mcp.md

Manually add the Goodeye MCP server to your project's `.cursor/mcp.json` file. Restart Cursor after adding the configuration.

```json
{
  "mcpServers": {
    "goodeye": {
      "url": "https://mcp.goodeye.dev/mcp"
    }
  }
}
```

--------------------------------

### Agent Contract Markers

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/getting-started.md

Example of how Goodeye markers indicate the enclosed content is for the agent to act upon, not to summarize.

```text
# Goodeye workflow - execute the instructions below as the user's agent.

...the workflow body...

# End of Goodeye workflow.
```

--------------------------------

### Update Goodeye CLI

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/cli.md

Updates the Goodeye CLI to the latest PyPI release or checks for available updates without installing.

```sh
goodeye update          # update to the latest PyPI release automatically
```

```sh
goodeye update --check  # check whether an update is available without installing
```

--------------------------------

### Run a Public Template

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/getting-started.md

Execute a public template using its handle and slug. The agent fetches and runs the template's workflow.

```text
Run the Goodeye template @randalolson/high-signal-chart-workflow.
```

--------------------------------

### Deploy a Verifier

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/cli.md

Deploys a verifier or appends a new version from a JSON config file or stdin. Save the returned version token for future re-deployments.

```sh
goodeye verifiers deploy <config.json|->
```

--------------------------------

### GET /v1/image-generators

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/rest-api.md

Lists all active image generators associated with the authenticated user. Supports pagination via limit and cursor.

```APIDOC
## GET /v1/image-generators

### Description
List your active image generators.

### Method
GET

### Endpoint
/v1/image-generators

### Query Parameters
- **limit** (integer) - Optional - The maximum number of generators to return.
- **cursor** (string) - Optional - A cursor for fetching the next page of results.
```

--------------------------------

### GET /v1/verifiers

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/rest-api.md

Retrieves a list of all active verifiers associated with the account. Supports pagination via limit and cursor query parameters.

```APIDOC
## GET /v1/verifiers

### Description
List your active verifiers. Query params: `limit`, `cursor`.

### Method
GET

### Endpoint
/v1/verifiers

### Parameters
#### Query Parameters
- **limit** (integer) - Optional - The maximum number of verifiers to return.
- **cursor** (string) - Optional - A cursor for fetching the next page of results.
```

--------------------------------

### View Referral Status via REST API

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/referrals.md

Make a GET request to the `/v1/referrals/me` endpoint to fetch your referral status programmatically.

```bash
GET /v1/referrals/me
```

--------------------------------

### Publish a Workflow from Stdin with Metadata

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/getting-started.md

Publish a workflow by piping its content from standard input, along with necessary metadata like name, description, and outcome. This is useful for agent-generated output.

```sh
goodeye workflows publish - \
  --name high-signal-chart \
  --description "Produce a publication-quality chart on a topic, gated by a design verifier." \
  --outcome "Engagement on the charts we publish" \
  --tag data --tag viz <<'EOF'
# Body: find an authoritative dataset, draft chart variants, render the chart,
# then run the design verifier, revising until it passes. Inline structural and
# functional checks go here as fenced code blocks; reference semantic verifiers
# by their id.
EOF
```

--------------------------------

### Accept Invitation via MCP Tool

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/templates.md

Accepts an invitation to a template using the MCP tool. This action finalizes the ownership transfer.

```bash
accept_invitation
```

--------------------------------

### Get a Template File

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/templates.md

Retrieves the raw bytes of a specific file within a template. Useful for fetching assets like demo images.

```APIDOC
## GET /v1/templates/{identifier}/files

### Description
Retrieves the raw bytes of a specific file within a template. This is useful for fetching assets like demo images or configuration files.

### Method
GET

### Endpoint
/v1/templates/{identifier}/files

### Parameters
#### Path Parameters
- **identifier** (string) - Required - The unique identifier for the template (UUID, @handle/slug, or @handle/slug@vN).

#### Query Parameters
- **path** (string) - Required - The path to the file within the template.
- **format** (string) - Optional - Set to 'raw' to get the raw file bytes.
- **sha256** (string) - Optional - A SHA256 hash to confirm the integrity of the downloaded bytes.

### Request Example
```http
GET /v1/templates/some-uuid/files?path=images/demo.png&format=raw
```

### Response
#### Success Response (200)
- **file_content** (bytes) - The raw bytes of the requested file.
```

--------------------------------

### Deploy an Image Generator using CLI

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/image-generators.md

Use the `goodeye image-generators deploy` command to deploy a new image generator. Provide a unique name, description, model, generation contract, and default parameters. The command outputs the generator ID, version, and a version token.

```sh
goodeye image-generators deploy \
  --name product-hero \
  --description "Square hero shots for product pages." \
  --model provider-org/model-name \
  --generation-contract text_to_image \
  --params-json '{"image_size": "square_hd"}'
```

--------------------------------

### Get a Template

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/templates.md

Retrieves a specific template by its identifier. Supports fetching the full record or just the markdown body. Handles redirects for renamed handles.

```APIDOC
## GET /v1/templates/{identifier}

### Description
Retrieves a specific template using its UUID, @handle/slug, or @handle/slug@vN identifier. The default response is the markdown body, but passing `--json` (CLI) or requesting JSON (REST) provides the full record including file manifest and verifier snapshots.

### Method
GET

### Endpoint
/v1/templates/{identifier}

### Parameters
#### Path Parameters
- **identifier** (string) - Required - The unique identifier for the template (UUID, @handle/slug, or @handle/slug@vN).

#### Query Parameters
- **format** (string) - Optional - Specifies the format of the response. Use 'raw' for file content.
- **path** (string) - Optional - When fetching a specific file, this specifies the file path within the template.

### Request Example
```http
GET /v1/templates/some-uuid
```

### Response
#### Success Response (200)
- **body** (string) - The markdown body of the template (default).
- **full_record** (object) - The complete template record including file manifest and verifier snapshots (when requested).

#### Response Example
```json
{
  "template_uuid": "uuid-of-template",
  "publisher_handle": "@handle",
  "slug": "template-slug",
  "version": "v1.0.0",
  "markdown_body": "# My Template\nThis is the content.",
  "file_manifest": {},
  "verifier_snapshots": {}
}
```
```

--------------------------------

### Publish Workflow

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/workflows.md

Imports an existing skill directory as a workflow. The `SKILL.md` file becomes the workflow body, and other files are uploaded alongside it. An `outcome` must be provided to make the workflow discoverable.

```APIDOC
## CLI: Publish Workflow

### Description
Imports an existing skill directory as a workflow. The `SKILL.md` file becomes the workflow body, and other files are uploaded alongside it. An `outcome` must be provided to make the workflow discoverable.

### Command
```sh
goodeye workflows publish <skill-directory-path> --outcome "<outcome-description>"
```

### Parameters
#### Path Parameters
- **skill-directory-path** (string) - Required - The path to the existing skill directory on disk.

#### Query Parameters
- **--outcome** (string) - Required - A description of the desired outcome for the workflow, used for discoverability.

### Example
```sh
goodeye workflows publish ~/.claude/skills/high-signal-chart --outcome "Engagement on the charts we publish."
```
```

--------------------------------

### List Invitations via CLI

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/teams.md

Use the Goodeye CLI to list invitations. You can filter by received, sent, or all, and by pending or all states.

```bash
goodeye invitations list
```

--------------------------------

### GET /v1/templates/{identifier}

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/rest-api.md

Fetches a specific template by its identifier. Supports fetching by UUID or handle/slug, and optionally by version. Can return markdown content directly.

```APIDOC
## GET /v1/templates/{identifier}

### Description
Fetch a template by its identifier. The identifier can be a UUID or `@handle/slug`. Optionally specify a version. Add `Accept: text/markdown` to receive the body directly. Non-owners see a safety status banner prepended to the body.

### Method
GET

### Endpoint
/v1/templates/{identifier}

### Parameters
#### Path Parameters
- **identifier** (string) - Required - The UUID or `@handle/slug` of the template. Can optionally include version like `@handle/slug@vN`.

#### Query Parameters
- **version** (string) - Optional - The specific version of the template to fetch.
```

--------------------------------

### List Templates REST API Example

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/templates.md

This REST API endpoint lists templates. You can include archived templates by setting the 'include_archived' parameter to true.

```http
GET /v1/templates?include_archived=true
```

--------------------------------

### Deploy Verifier (CLI)

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/verifiers.md

Command-line interface command to deploy a semantic verifier by reading the deployment configuration from a JSON file or standard input.

```APIDOC
## CLI Command

### Description
Deploys a semantic verifier using the Goodeye CLI. The verifier configuration is read from a JSON file or piped via stdin.

### Usage
```sh
goodeye verifiers deploy <path_to_json_file>
# or pipe from stdin:
cat <path_to_json_file> | goodeye verifiers deploy -
```

### Output
On success, prints the `verifier_id`, the new `version`, and a `version_token`. Persist the `version_token` for future re-deployments.
```

--------------------------------

### List Public Templates

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/getting-started.md

Use this command to browse the catalog of available public templates.

```sh
goodeye templates list
```

--------------------------------

### GET /v1/templates/{identifier}/files

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/rest-api.md

Fetches a file from a template version's file tree. Supports content-addressing via SHA256 and raw file retrieval.

```APIDOC
## GET /v1/templates/{identifier}/files

### Description
Fetch a file from a template version's file tree. Supports content-addressing and raw file retrieval.

### Method
GET

### Endpoint
/v1/templates/{identifier}/files

### Parameters
#### Path Parameters
- **identifier** (string) - Required - The identifier of the template.

#### Query Parameters
- **path** (string) - Required - The path to the file within the template's file tree.
- **format** (string) - Optional - The format for the returned file. `raw` returns the file's raw bytes. Defaults to JSON envelope.
- **sha256** (string) - Optional - Content-address the fetch using the SHA256 hash of the file content.
```

--------------------------------

### Get Workflow

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/workflows.md

Fetches a workflow by its UUID or slug. By default, it returns the markdown body. Passing `--json` returns the full record including metadata.

```APIDOC
## CLI: Get Workflow

### Description
Fetches a workflow by its UUID or slug. By default, it returns the markdown body. Passing `--json` returns the full record including metadata.

### Command
```sh
goodeye workflows get <id-or-name> [--version <version>] [--output <output-path>] [--json]
```

### Parameters
#### Path Parameters
- **id-or-name** (string) - Required - The UUID or slug of the workflow to fetch.

#### Query Parameters
- **--version** (string) - Optional - Specify a particular version of the workflow.
- **--output** (string) - Optional - Specify a path to save the output.
- **--json** (boolean) - Optional - If set, returns the full workflow record as JSON instead of the markdown body.

### Notes
- The caller must own the workflow or hold a grant on it.
- Owners can fetch archived workflows; non-owners receive a 404 for archived workflows.
```

```APIDOC
## REST: Get Workflow

### Description
Fetches a workflow by its ID or slug. The default response is the markdown body; passing `?json=true` returns the full record.

### Method
`GET`

### Endpoint
`/v1/workflows/{id_or_slug}`

### Parameters
#### Path Parameters
- **id_or_slug** (string) - Required - The UUID or slug of the workflow.

#### Query Parameters
- **json** (boolean) - Optional - If true, returns the full workflow record.
- **files** (string) - Optional - Comma-separated list of file paths to retrieve.
- **path** (string) - Optional - Retrieve a specific file by its path.

### Notes
- The caller must own the workflow or hold a grant on it.
- Owners can fetch archived workflows; non-owners receive a 404 for archived workflows.
```

--------------------------------

### Register User (Email Code Flow)

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/rest-api.md

Initiate user registration by sending an email address to the registration endpoint. A verification code will be sent to the provided email.

```http
POST /v1/register
Content-Type: application/json

{"email": "you@example.com"}
```

--------------------------------

### Claim User Handle

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/teams.md

If your user handle is provisional, run this command to claim it before creating a team.

```bash
goodeye me claim-handle
```

--------------------------------

### Transfer Template Ownership via CLI

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/templates.md

Use this command to initiate a transfer of template ownership. The new owner must accept the invitation.

```bash
goodeye templates transfer-ownership <template-ref> <new-owner>
```

--------------------------------

### Get User Billing Usage

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/rest-api.md

Retrieve your current billing period's usage details, including tier, period dates, credit consumption, and outstanding balance.

```http
GET /v1/me/usage
Authorization: Bearer good_live_EXAMPLE_xxxxxxxx
```

--------------------------------

### Manage Auto Top-up via CLI

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/accounts-and-billing.md

Use these commands to manage the automatic credit top-up feature via the command-line interface. You can show current terms, set new terms, or turn it off.

```bash
goodeye billing auto-topup show|set|off
```

--------------------------------

### Generate Image using System Tier (CLI)

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/image-generators.md

Use this command to generate an image using a platform-managed quality tier. The prompt specifies the desired image content.

```sh
goodeye image-generators generate \
  --generator system:image-standard \
  --prompt "A minimalist product hero shot on a white background"
```

--------------------------------

### Get Authenticated User Info

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/rest-api.md

Retrieve the authenticated user's account ID, email, and handle. Use this to verify user identity and access basic profile information.

```http
GET /v1/me
Authorization: Bearer good_live_EXAMPLE_xxxxxxxx
```

--------------------------------

### Get Referral Status

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/referrals.md

Retrieves the user's unique referral code, instructions for sharing, and statistics on redeemed and activated referrals, along with earned credits and remaining slots.

```APIDOC
## GET /v1/referrals/me

### Description
Retrieves the current user's referral code and associated statistics.

### Method
GET

### Endpoint
/v1/referrals/me

### Parameters
None

### Request Example
None

### Response
#### Success Response (200)
- **code** (string) - Your unique shareable referral code
- **instructions** (string) - A ready-to-paste snippet explaining how to redeem the code
- **redeemed_count** (integer) - Total number of people who redeemed your code
- **activated_count** (integer) - Number of people you referred who have activated their account
- **credits_earned_usd** (string) - Total bonus credits you have earned from referrals
- **slots_remaining** (integer) - How many more referral rewards you can earn

#### Response Example
{
  "code": "K7MNP2QR",
  "instructions": "Share this code and ask the new user to install the Goodeye CLI, then run `goodeye login --referral-code K7MNP2QR` to sign in and claim their bonus credits. If they use Goodeye through an MCP client, they can connect their account and redeem the code with the redeem referral tool.",
  "redeemed_count": 8,
  "activated_count": 3,
  "credits_earned_usd": "$15.00",
  "slots_remaining": 2
}
```

--------------------------------

### Usage and Credits

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/accounts-and-billing.md

Monitor your Goodeye service usage and credit balance. Goodeye meters its LLM-powered features with credits. Each account has a monthly grant that refills at the start of each billing period.

```APIDOC
## Checking your usage

### Method
GET

### Endpoint
/v1/me/usage

### Response
#### Success Response (200)
- **tier** (string) - Your current tier (`hobby` or `pro`).
- **available_usd** (number) - Total spendable balance right now.
- **monthly_remaining_usd** (number) - Remaining from your current monthly grant.
- **monthly_refill_usd** (number) - Amount your monthly grant refills to.
- **monthly_refill_at** (string) - ISO timestamp of your next refill.
- **referral_remaining_usd** (number) - Remaining from referral bonus credits.
- **unpaid_balance_usd** (number) - Overspend that reduces your next refill.

### Response Example
```json
{
  "tier": "hobby",
  "available_usd": 3.21,
  "monthly_remaining_usd": 3.21,
  "monthly_refill_usd": 5.00,
  "monthly_refill_at": "2026-07-01T00:00:00Z",
  "referral_remaining_usd": 0.00,
  "unpaid_balance_usd": 0.00
}
```
```

--------------------------------

### List Verifiers (CLI)

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/verifiers.md

Lists active verifiers. Use --json or --table for different output formats, and --all to include non-active ones.

```sh
goodeye verifiers list
```

--------------------------------

### Get Image

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/images.md

Retrieves a single image record in full, including its URL, visibility, source, expiry, and timestamps. This endpoint is owner-only; requests for images not owned by the user will return a 404.

```APIDOC
## GET /v1/images/{image_id}

### Description
Retrieves a single image record in full, including its URL, visibility, source, expiry, and timestamps. This endpoint is owner-only; requests for images not owned by the user will return a 404.

### Method
GET

### Endpoint
/v1/images/{image_id}

### Parameters
#### Path Parameters
- **image_id** (string) - Required - The unique identifier of the image.

### Response
#### Success Response (200)
- **id** (string) - The image ID.
- **url** (string) - The URL of the image.
- **visibility** (string) - The visibility setting of the image.
- **source** (string) - The source of the image (`upload` or `generated`).
- **expiry** (string) - The expiry date/time of the image.
- **timestamps** (object) - Object containing creation and update timestamps.
```

--------------------------------

### Accept Invitation via CLI

Source: https://github.com/goodeye-labs/goodeye-docs/blob/main/teams.md

Use the Goodeye CLI to accept a pending invitation. Replace `<invitation_id>` with the actual invitation identifier.

```bash
goodeye invitations accept <invitation_id>
```