> ## Documentation Index
> Fetch the complete documentation index at: https://docs.peepsai.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Command reference

> Every Peeps MCP command, grouped by the job you want done: what it does, what to ask your agent, the permission it needs, and whether it changes anything.

You never have to name a command. Ask in plain English and your agent picks the right ones. This page is for knowing what is possible, and for recognizing a command when your agent asks you to approve it.

The groups are in the order most people need them.

## How to read the tables

**Needs** is the permission your connection must carry. See [the five permissions](/mcp/access-and-approvals#the-five-permissions). "Contributor" means you also need the Contributor role or above in the organization.

**Effect** says what the command does to Peeps:

| Effect | What it means |
| - | - |
| **Reads** | Changes nothing. |
| **Changes Peeps** | Creates or edits something in Peeps. Your agent asks you first. |
| **Runs CI** | Starts a real run in Peeps's hosted CI, using a plan you approved. |
| **Changes what runs** | Changes which script your future runs use. You approve the exact change. |

## Workflows

Peeps also serves three ready-made workflows as MCP prompts. They chain the commands below for the most common jobs.

| Prompt | What it does | Try asking |
| - | - | - |
| `peeps-troubleshoot` | Diagnoses a failing test from a Peeps URL or id, checks it against your checkout, and branches on the diagnosis. | "Troubleshoot this failure: (Peeps URL)" |
| `peeps-cover` | Compares your code change with existing coverage and proposes cases for real gaps. | "Is what I changed on this branch covered?" |
| `peeps-import` | Imports your existing Playwright tests, keeping each file as its case's script. | "Import my Playwright tests into Peeps." |

## Connect and find your project

| Command | What it does | Try asking | Needs | Effect |
| - | - | - | - | - |
| `whoami` | Shows your organizations, your role in each, whether MCP is on, and what your connection allows. | "Who am I in Peeps?" | Any connection | Reads |
| `resolve_project` | Finds the Peeps project linked to this checkout's GitHub repository. | "Which Peeps project is this repo?" | Read | Reads |
| `list_projects` | Lists the projects you can reach, each with its organization. | "Which Peeps projects can I see?" | Read | Reads |
| `get_project` | Reads one project's name, identifier, platform and organization. | "What's this project's identifier?" | Read | Reads |

## Understand failures

| Command | What it does | Try asking | Needs | Effect |
| - | - | - | - | - |
| `list_failures` | Lists the tests failing now in a project, newest first. | "What's failing in Peeps this week?" | Read | Reads |
| `inspect_failure` | Opens one failure in full: analysis, exact error, the script that ran, history and dependencies. | "Why did the checkout test fail on staging last night?" | Read | Reads |
| `get_batch_summary` | Summarizes a batch run and lists every member failing in it now. | "Summarize last night's regression batch." | Read | Reads |
| `get_artifact` | Fetches one screenshot, trace, video, DOM snapshot or network summary from a run. | "Show me the page at the moment it failed." | Read | Reads |

See [troubleshoot and fix a failure](/mcp/troubleshoot-and-fix).

## Fix a failing test

A fix starts with a fix plan from `get_execution_plan`, listed under [run tests](#run-tests).

| Command | What it does | Try asking | Needs | Effect |
| - | - | - | - | - |
| `submit_fix` | Sends a fix you approved for Peeps to verify in its own hosted run. It doesn't publish. | "Verify that fix on staging." | Edit, Run · Contributor | Runs CI |
| `get_verification_status` | Follows a fix verification to its result. | "Did the fix pass?" | Read | Reads |
| `get_verified_fix_review` | Shows the complete review of a verified fix: script and step changes, target and production impact. | "Show me the fix before I publish it." | Read | Reads |
| `publish_verified_fix` | Publishes a verified fix, so every future run uses it. | "Publish the fix." | Edit, Publish · Contributor | Changes what runs |
| `recheck_verified_fix` | Runs a verified fix again when the environment or the tests around it changed. | "Recheck the fix against today's staging." | Edit, Run · Contributor | Runs CI |
| `dismiss_verified_fix` | Retires a suggested fix you don't want. Its history stays. | "Dismiss that fix." | Edit · Contributor | Changes Peeps |
| `update_test_steps` | Replaces a test case's steps when what the product should do has changed. | "Add the delivery-date step to the checkout test." | Edit · Contributor | Changes Peeps |

## Run tests

| Command | What it does | Try asking | Needs | Effect |
| - | - | - | - | - |
| `get_execution_plan` | Prepares the plan you approve before a run, a fix verification or a script generation. It starts nothing. | "What would running the login test on staging involve?" | Read | Reads |
| `run_test` | Runs a test case in Peeps's hosted CI, using the plan you approved. | "Run the checkout test against staging." | Run | Runs CI |
| `get_run_status` | Follows a run to its result. | "Has that run finished?" | Read | Reads |

See [run tests](/mcp/run-tests).

## Find tests and coverage

| Command | What it does | Try asking | Needs | Effect |
| - | - | - | - | - |
| `search_test_cases` | Searches test case titles and steps, optionally within a folder or including archived cases. | "Do we have a test for guest checkout?" | Read | Reads |
| `get_test_case` | Reads one test case in full: details, steps, what runs before and after it, and its cleanup test. | "Show me the steps for the password reset test." | Read | Reads |
| `list_folders` | Lists a project's folders with how many test cases each holds. | "What folders does this project have?" | Read | Reads |

See [find tests and check coverage](/mcp/find-tests).

## Create tests

| Command | What it does | Try asking | Needs | Effect |
| - | - | - | - | - |
| `create_test_cases` | Creates the test cases you approved, up to 50 per call. No script is written and nothing runs. | "Create tests for the gaps you found." | Edit · Contributor | Changes Peeps |
| `generate_and_publish_script` | Generates a test case's script by driving your app in a hosted browser, then publishes it. | "Generate a script for the new password reset test on staging." | Edit, Run, Publish · Contributor | Changes what runs |
| `get_generation_status` | Follows a script generation, and says whether each script was published or kept as a draft. | "Is the new script ready?" | Read | Reads |

See [create and import tests](/mcp/create-and-import).

## Import existing tests

Your agent chains these for you, through the `peeps-import` workflow.

| Command | What it does | Try asking | Needs | Effect |
| - | - | - | - | - |
| `prepare_script_import` | Starts an import and moves it through its stages, up to the review. | "Import the tests in `e2e/checkout/` into Peeps." | Edit · Contributor | Changes Peeps |
| `upload_script_import` | Sends the test files you approved to the import. | Part of an import | Edit · Contributor | Changes Peeps |
| `get_script_import` | Shows an import's progress and the review of each case. | "How is the import going?" | Read | Reads |
| `commit_script_import` | Creates the test cases you approved, and publishes their scripts if you approved that too. | "Import those five cases and publish them." | Edit · Contributor, plus Publish to publish | Changes Peeps, or changes what runs when publishing |
| `cancel_script_import` | Stops an import's remaining work. Cases already created stay. | "Cancel the import." | Edit · Contributor | Changes Peeps |
| `attach_import_source` | Where your organization keeps the source of converted tests, sends the original files before your agent writes steps from them. | "Turn these Playwright tests into Peeps steps." | Edit · Contributor | Stores the files |

## Manage scripts

| Command | What it does | Try asking | Needs | Effect |
| - | - | - | - | - |
| `list_test_scripts` | Lists a test case's script versions and marks the one a run would use. | "Which script version does the login test run?" | Read | Reads |
| `get_script` | Reads one script version's source, with secrets masked. | "Show me the login test's script." | Read | Reads |
| `add_test_script` | Adds a draft script version to one test case. | "Add this as a new version of the login test's script." | Edit · Contributor | Changes Peeps |
| `add_test_scripts` | Adds up to 20 draft scripts at once, and can publish them onto cases that have no script yet. | "Add these scripts to the new cases and publish them." | Edit · Contributor, plus Publish to publish | Changes Peeps, or changes what runs when publishing |
| `publish_test_script` | Publishes a draft, so every future run uses it. | "Publish the new login script." | Edit, Publish · Contributor | Changes what runs |
| `archive_test_script` | Archives a script version. | "Archive the old version of the login script." | Edit · Contributor, plus Publish for the version that runs | Changes Peeps, or changes what runs |
| `unarchive_test_script` | Restores an archived script version. | "Restore the previous login script." | Edit, Publish · Contributor | Changes what runs |
| `prepare_language_change` | Prepares converting a test's script between JavaScript or TypeScript and Python, for you to approve in a form. | "Convert the login test to Python." | Edit, Run · Contributor | Changes Peeps |
| `verify_language_change` | Runs the approved conversion in Peeps's hosted CI. It doesn't publish. | "Verify the Python version." | Edit, Run · Contributor | Runs CI |
| `get_language_change_status` | Shows whether the conversion verified. | "Did the conversion pass?" | Read | Reads |
| `publish_language_change` | Publishes a verified conversion. | "Publish the Python version." | Edit, Run, Publish · Contributor | Changes what runs |

A conversion you prepare for publishing also needs **Publish** at the prepare and verify steps. See [manage scripts](/mcp/manage-tests#manage-scripts).

## Organize and maintain tests

| Command | What it does | Try asking | Needs | Effect |
| - | - | - | - | - |
| `update_test_case_metadata` | Changes a test case's title, description, expected result, priority, type or approach. | "Mark the checkout tests as critical priority." | Edit · Contributor | Changes Peeps |
| `update_test_dependencies` | Sets which test cases run before one or more others. | "Make order history run after 'Place an order'." | Edit · Contributor | Changes Peeps |
| `preview_cleanup_companion_changes` | Previews a cleanup test change: every link and every affected test. | "What would change if 'Delete the test project' cleaned up after 'Create a project'?" | Read | Reads |
| `update_cleanup_companions` | Applies the cleanup change you approved from the preview. | "Apply that cleanup change." | Edit · Contributor | Changes Peeps |
| `archive_test_cases` | Archives up to 50 test cases, optionally with their runs. | "Archive the guest-checkout tests and their runs." | Edit · Contributor | Changes Peeps |
| `unarchive_test_cases` | Restores up to 50 archived test cases, and the runs archived with them. | "Restore the guest-checkout tests." | Edit · Contributor | Changes Peeps |
| `create_folder` | Creates a folder, at the top level or inside another. | "Create a Payments folder." | Edit · Contributor | Changes Peeps |
| `rename_folder` | Renames a folder in place, so suites that name it keep it. | "Rename Payments to Billing." | Edit · Contributor | Changes Peeps |
| `move_folder` | Moves a folder, with everything in it, under another folder or to the top. | "Move Billing under Account." | Edit · Contributor | Changes Peeps |
| `delete_folder` | Deletes an empty folder. | "Delete the empty Legacy folder." | Edit · Contributor | Changes Peeps |
| `move_test_cases_to_folder` | Files up to 500 test cases into a folder, or takes them out of any folder. | "Move the refund tests into Billing." | Edit · Contributor | Changes Peeps |

See [manage tests](/mcp/manage-tests).

## Environments

| Command | What it does | Try asking | Needs | Effect |
| - | - | - | - | - |
| `list_environments` | Lists environments with their variables' names and types, never values. Can compare a value you give with the stored one. | "What variables does staging have?" | Read, plus Edit · Contributor to compare | Reads |
| `create_environment` | Creates an environment with its variables. | "Create a QA environment for `https://qa.example.com`." | Edit · Contributor | Changes Peeps |
| `set_environment_variable` | Adds a variable, or changes an existing one. | "Set `ADMIN_EMAIL` in staging." | Edit · Contributor | Changes Peeps |
| `update_environment` | Renames an environment, changes its description, or makes it the default. | "Rename PREVIEW to STAGING and make it the default." | Edit · Contributor | Changes Peeps |
| `delete_environment_variable` | Deletes one variable from an environment. | "Remove `LEGACY_TOKEN` from staging." | Edit · Contributor | Changes Peeps |

## Projects

| Command | What it does | Try asking | Needs | Effect |
| - | - | - | - | - |
| `create_project` | Creates a web project, with one empty environment. | "Set up a Peeps project for this app." | Edit · Contributor | Changes Peeps |
| `update_project` | Renames a project or changes its description. | "Rename this project to Storefront." | Edit · Contributor | Changes Peeps |

See [environments and projects](/mcp/environments-and-projects).

## Linear

| Command | What it does | Try asking | Needs | Effect |
| - | - | - | - | - |
| `list_linear_issues` | Lists the Linear issues linked to a test case, run or batch run. | "Is there a Linear issue for this failure?" | Read | Reads |
| `link_linear_issue` | Links a Linear issue, and adds a Peeps attachment to it in Linear. | "Link ENG-123 to this run." | Edit · Contributor | Changes Peeps and Linear |
| `unlink_linear_issue` | Unlinks a Linear issue, and removes the Peeps attachment from it. | "Unlink ENG-123 from the checkout test." | Edit · Contributor | Changes Peeps and Linear |

See [Linear issues](/mcp/linear-issues).