# CI integration
Source: https://docs.getlark.ai/ci

Run testing workflows as part of your deployment pipeline.

## Configuring CI

You can use the [Lark CLI](/cli) to run your testing workflows as part of your deployment. The `--wait` flag blocks until every workflow finishes and exits with a non-zero code on failure, so your pipeline fails if a test fails.

Set the `GETLARK_API_KEY` environment variable in your CI provider's secrets settings before adding the steps below.

### GitHub Actions

```yaml theme={null}
- name: Run Lark Tests
  run: npx -y @getlark/cli workflows invoke --all --wait
  env:
    GETLARK_API_KEY: ${{ secrets.GETLARK_API_KEY }}
```

### CircleCI

```yaml theme={null}
lark_tests:
  docker:
    - image: cimg/node:lts
  resource_class: small
  steps:
    - run:
        name: Run Lark Tests
        command: npx -y @getlark/cli workflows invoke --all --wait
```

### GitLab CI

```yaml theme={null}
lark_tests:
  image: node:lts
  script:
    - npx -y @getlark/cli workflows invoke --all --wait
```

<Tip>
  Each provider stores secrets in a different place. Add `GETLARK_API_KEY` under:

  * **GitHub Actions**: Settings → Secrets and variables → Actions
  * **CircleCI**: Project Settings → Environment Variables
  * **GitLab CI**: Settings → CI/CD → Variables
</Tip>


# CLI
Source: https://docs.getlark.ai/cli

Use the CLI to manage testing workflows from the terminal.

The [Lark CLI](https://www.npmjs.com/package/@getlark/cli) lets you create workflows, invoke them, poll for results, and retrieve execution logs from your terminal or CI pipeline.

## Installation

Requires Node.js 18 or later. Run directly with `npx`:

```bash theme={null}
npx -y @getlark/cli workflows invoke --all --wait
```

Or install globally:

```bash theme={null}
npm install -g @getlark/cli
```

## Authentication

The fastest way to authenticate is `getlark login`:

```bash theme={null}
getlark login                          # prompts for your API key
getlark login --api-key your-api-key   # non-interactive
```

This stores your credentials at `~/.getlark/config.json` (mode `0600`) so subsequent commands work in any new shell — no need to reload your shell or re-export an env var. Run `getlark logout` to remove the stored credentials.

The CLI resolves the API key in this order:

1. `--api-key` flag
2. `GETLARK_API_KEY` environment variable
3. `~/.getlark/config.json`
4. error

The same precedence applies to `--api-url` / `GETLARK_API_URL`. CI usage is unchanged — keep using the env var.

The CLI also supports a `.env` file in the current directory.

<Info>
  Create and manage API keys in the [dashboard](https://dashboard.getlark.ai/settings/api-keys). Copy the key when you create it — you only see the full value once.
</Info>

## Global options

| Flag               | Description                                                     |
| ------------------ | --------------------------------------------------------------- |
| `--api-key <key>`  | API key (overrides `GETLARK_API_KEY` env var and stored config) |
| `--profile <name>` | Profile to read from `~/.getlark/config.json`                   |
| `-V, --version`    | Display the CLI version                                         |
| `-h, --help`       | Display help for any command                                    |

## Workflows

Create, update, list, archive, and invoke workflows. See the dedicated sections below for executions, repairs, and generations.

### Create a workflow

```bash theme={null}
getlark workflows create --name "login-flow" --description "Test the login process end-to-end"
```

| Flag                           | Required | Description                                  | Default     |
| ------------------------------ | -------- | -------------------------------------------- | ----------- |
| `--name <name>`                | Yes      | Workflow name                                |             |
| `--description <text>`         | Yes      | Workflow description                         |             |
| `--mode <mode>`                | No       | `ai_driven` or `deterministic`               | `ai_driven` |
| `--secret-contexts <names...>` | No       | Secret contexts to attach                    |             |
| `--group-id <id>`              | No       | Workflow group ID to assign this workflow to |             |

```bash theme={null}
getlark workflows create \
  --name "checkout-flow" \
  --description "Test the full checkout process" \
  --mode deterministic \
  --secret-contexts production staging
```

### Get workflow details

```bash theme={null}
getlark workflows get <workflow_id>
```

Returns the full workflow resource including status, mode, schedule, and last execution/generation/repair info.

### Update a workflow

```bash theme={null}
getlark workflows update <workflow_id> --name "new-name" --description "updated description"
```

| Flag                           | Description                               |
| ------------------------------ | ----------------------------------------- |
| `--name <name>`                | New name for the workflow                 |
| `--description <text>`         | New description for the workflow          |
| `--secret-contexts <names...>` | Secret contexts to attach                 |
| `--schedule <cron>`            | Cron schedule for the workflow            |
| `--group-id <id>`              | Workflow group ID (use `null` to ungroup) |

At least one option is required.

### Archive a workflow

```bash theme={null}
getlark workflows archive <workflow_id>
```

Archived workflows are hidden from the default list and cannot be invoked until unarchived.

### Unarchive a workflow

```bash theme={null}
getlark workflows unarchive <workflow_id>
```

Restores an archived workflow so it appears in the list and can be invoked again.

### List workflows

```bash theme={null}
getlark workflows list
```

| Flag              | Description                     | Default |
| ----------------- | ------------------------------- | ------- |
| `--limit <n>`     | Max workflows to return (1–100) | `10`    |
| `--offset <n>`    | Number of workflows to skip     | `0`     |
| `--group-id <id>` | Filter workflows by group ID    |         |

### Invoke workflows

Run one or more workflows and optionally wait for them to finish. One of `--workflow-ids`, `--all`, `--group-id`, or `--group-name` is required.

```bash theme={null}
# Invoke all workflows and wait (up to 5 minutes) for completion
getlark workflows invoke --all --wait --timeout 300

# Invoke specific workflows and wait
getlark workflows invoke --workflow-ids wf_abc123 wf_def456 --wait --timeout 300

# Invoke all workflows in a group by ID
getlark workflows invoke --group-id wfl_grp_abc123 --wait

# Invoke all workflows in a group by name
getlark workflows invoke --group-name "Checkout Flow" --wait
```

| Flag                      | Description                                                    |
| ------------------------- | -------------------------------------------------------------- |
| `--workflow-ids <ids...>` | IDs of the workflows to invoke                                 |
| `--all`                   | Invoke all workflows                                           |
| `--group-id <id>`         | Invoke all workflows in a group (by group ID)                  |
| `--group-name <name>`     | Invoke all workflows in a group (by group name)                |
| `--wait`                  | Block until every execution finishes                           |
| `--timeout <seconds>`     | Maximum wait time in seconds (default: 600, requires `--wait`) |
| `--verbose`               | Print verbose output including logs                            |

#### Exit codes

| Code | Meaning                       |
| ---- | ----------------------------- |
| `0`  | All workflows passed          |
| `1`  | One or more workflows failed  |
| `2`  | Timed out waiting for results |
| `3`  | Unexpected error              |

### List workflow events

```bash theme={null}
getlark workflows events list <workflow_id>
```

| Flag           | Description                  | Default |
| -------------- | ---------------------------- | ------- |
| `--limit <n>`  | Max events to return (1–100) | `10`    |
| `--offset <n>` | Number of events to skip     | `0`     |

Lists all events (generations, executions, repairs) for a workflow.

## Executions

Inspect, follow, and cancel individual runs of a workflow.

### Get execution details

```bash theme={null}
getlark workflows executions get <workflow_id> <execution_id>
```

### Get execution logs

```bash theme={null}
getlark workflows executions logs <workflow_id> <execution_id>
```

### Cancel a running execution

```bash theme={null}
getlark workflows executions cancel <workflow_id> <execution_id>
```

## Repairs

Trigger and inspect AI repair attempts on a workflow after a failed execution.

### Trigger a workflow repair

```bash theme={null}
getlark workflows repairs trigger <workflow_id>
```

Triggers a repair for a workflow. Returns the repair resource.

### List workflow repairs

```bash theme={null}
getlark workflows repairs list <workflow_id>
```

| Flag           | Description                   | Default |
| -------------- | ----------------------------- | ------- |
| `--limit <n>`  | Max repairs to return (1–100) | `10`    |
| `--offset <n>` | Number of repairs to skip     | `0`     |

### Get repair details

```bash theme={null}
getlark workflows repairs get <workflow_id> <repair_id>
```

### Cancel a running repair

```bash theme={null}
getlark workflows repairs cancel <workflow_id> <repair_id>
```

### Get repair logs

```bash theme={null}
getlark workflows repairs logs <workflow_id> <repair_id>
```

## Generations

Manage in-progress workflow generations (the background process that produces a workflow's executable artifact when it's created or substantially edited).

### Cancel a running generation

```bash theme={null}
getlark workflows generations cancel <workflow_id> <generation_id>
```

## Workflow groups

Group related workflows together for organization and bulk filtering.

### Create a workflow group

```bash theme={null}
getlark workflow-groups create --name "Checkout Flow"
```

| Flag            | Required | Description                |
| --------------- | -------- | -------------------------- |
| `--name <name>` | Yes      | Name of the workflow group |

### List workflow groups

```bash theme={null}
getlark workflow-groups list
```

| Flag           | Description                  | Default |
| -------------- | ---------------------------- | ------- |
| `--limit <n>`  | Max groups to return (1–100) | `10`    |
| `--offset <n>` | Number of groups to skip     | `0`     |

### Get a workflow group

```bash theme={null}
getlark workflow-groups get <group_id>
```

### Update a workflow group

```bash theme={null}
getlark workflow-groups update <group_id> --name "Updated Name"
```

| Flag            | Description                     |
| --------------- | ------------------------------- |
| `--name <name>` | New name for the workflow group |

### Delete a workflow group

```bash theme={null}
getlark workflow-groups delete <group_id>
```

Workflows in the group become ungrouped.

## Jobs

Asynchronous bulk operations on workflows (currently `workflow_import`). Submit a job, then poll `getlark jobs get` until it reaches a terminal state (`completed`, `failed`, or `cancelled`).

### Create a job from an inline JSON input file

```bash theme={null}
getlark jobs create --name "Import workflows" --input-file ./workflows.json
```

| Flag                  | Required | Description                                               | Default           |
| --------------------- | -------- | --------------------------------------------------------- | ----------------- |
| `--name <name>`       | Yes      | Human-readable name for the job                           |                   |
| `--input-file <path>` | Yes      | Path to a JSON file with the job input (see schema below) |                   |
| `--type <type>`       | No       | Job type. Currently only `workflow_import` is supported.  | `workflow_import` |

#### `workflow_import` input file schema

The input file is a single JSON object. The same file is accepted by `jobs create`, `jobs upload`, and `jobs validate`.

Top-level object:

| Field       | Type                      | Required | Description                                                       |
| ----------- | ------------------------- | -------- | ----------------------------------------------------------------- |
| `workflows` | array of workflow entries | Yes      | One or more workflows to import. Must contain at least one entry. |

Each entry under `workflows`:

| Field             | Type                               | Required | Description                                                                                   |
| ----------------- | ---------------------------------- | -------- | --------------------------------------------------------------------------------------------- |
| `name`            | non-empty string                   | Yes      | Workflow name.                                                                                |
| `description`     | non-empty string                   | Yes      | Workflow description; the AI agent reads this at runtime to perform the test.                 |
| `mode`            | `"ai_driven"` \| `"deterministic"` | Yes      | Execution mode for the workflow.                                                              |
| `secret_contexts` | array of unique strings \| `null`  | No       | Secret context names the workflow may use. Omit or set `null` for none.                       |
| `group_id`        | string \| `null`                   | No       | ID of the workflow group to assign the workflow to. Omit or set `null` to leave it ungrouped. |

No additional properties are accepted at the top level or per workflow.

Example `workflows.json`:

```json theme={null}
{
  "workflows": [
    {
      "name": "Checkout smoke",
      "description": "Verify checkout works end-to-end with a test card.",
      "mode": "ai_driven",
      "secret_contexts": ["staging"],
      "group_id": "wfl_grp_abc123"
    },
    {
      "name": "Login regression",
      "description": "Log in with seeded credentials and confirm the dashboard loads.",
      "mode": "deterministic"
    }
  ]
}
```

<Tip>
  Run `getlark jobs validate --file ./workflows.json` before submitting to catch schema errors without creating a job.
</Tip>

### List jobs

```bash theme={null}
getlark jobs list --status pending --status running
```

| Flag                | Description                                                                             | Default |
| ------------------- | --------------------------------------------------------------------------------------- | ------- |
| `--limit <n>`       | Max jobs to return (1–100)                                                              | `20`    |
| `--offset <n>`      | Number of jobs to skip                                                                  | `0`     |
| `--status <status>` | Filter by status (`pending`, `running`, `completed`, `failed`, `cancelled`); repeatable |         |

### Get a job

```bash theme={null}
getlark jobs get <job_id>
```

### Cancel a job

```bash theme={null}
getlark jobs cancel <job_id>
```

Cancels a pending or running job.

### Upload a job from a file

```bash theme={null}
getlark jobs upload --name "Import workflows" --file ./workflows.json
```

| Flag            | Required | Description                                                                                 | Default           |
| --------------- | -------- | ------------------------------------------------------------------------------------------- | ----------------- |
| `--name <name>` | Yes      | Human-readable name for the job                                                             |                   |
| `--file <path>` | Yes      | Path to the input file (same schema as [`jobs create`](#workflow_import-input-file-schema)) |                   |
| `--type <type>` | No       | Job type. Currently only `workflow_import` is supported.                                    | `workflow_import` |

Sends the file as `multipart/form-data` to `/jobs/upload`. The job stores the original filename so you can retrieve it later from `getlark jobs get`.

### Validate an input file without creating a job

```bash theme={null}
getlark jobs validate --file ./workflows.json
```

| Flag            | Required | Description                                                                                 | Default           |
| --------------- | -------- | ------------------------------------------------------------------------------------------- | ----------------- |
| `--file <path>` | Yes      | Path to the input file (same schema as [`jobs create`](#workflow_import-input-file-schema)) |                   |
| `--type <type>` | No       | Job type. Currently only `workflow_import` is supported.                                    | `workflow_import` |

Prints the validation report and exits non-zero if `valid: false`.

## Secret contexts

Manage credentials that workflows reference at runtime. Values are encrypted at rest and never returned by the API.

### List secret contexts

```bash theme={null}
getlark secret-contexts list
```

Returns all secret context names and metadata for your account. Does not return secret values.

### Get a secret context

```bash theme={null}
getlark secret-contexts get <context>
```

Returns the context name and the list of key names stored in it. Does not return secret values.

### Create or replace a secret context

```bash theme={null}
getlark secret-contexts create --context production --secret username=admin --secret password=s3cret
```

| Flag                   | Required | Description                                        |
| ---------------------- | -------- | -------------------------------------------------- |
| `--context <name>`     | Yes      | Name of the secret context                         |
| `--secret <key=value>` | Yes      | Secret key-value pair (repeat for multiple values) |

```bash theme={null}
getlark secret-contexts create \
  --context staging \
  --secret api_key=sk_test_abc123 \
  --secret username=testuser \
  --secret password=testpass
```

### Update a key in a secret context

```bash theme={null}
getlark secret-contexts update <context> --key <key> --value <value>
```

| Flag              | Required | Description                 |
| ----------------- | -------- | --------------------------- |
| `--key <name>`    | Yes      | The key to create or update |
| `--value <value>` | Yes      | The new value for the key   |

If the key already exists its value is replaced; if it does not exist it is added.

### Delete a secret context

```bash theme={null}
getlark secret-contexts delete <context>
```

Permanently deletes a secret context. Workflows referencing it will no longer have access.

### Delete a key from a secret context

```bash theme={null}
getlark secret-contexts delete-key <context> <key>
```

Removes a single key-value pair from an existing secret context.

## Examples

```bash theme={null}
# Create a workflow
getlark workflows create --name "signup-flow" --description "Test user signup"

# Get workflow details
getlark workflows get wf_abc123

# Update a workflow
getlark workflows update wf_abc123 --name "updated-signup-flow" --schedule "0 9 * * *"

# List your workflows
getlark workflows list --limit 20

# List workflows in a group
getlark workflows list --group-id grp_abc123

# Archive a workflow
getlark workflows archive wf_abc123

# Unarchive a workflow
getlark workflows unarchive wf_abc123

# Invoke a workflow without waiting
getlark workflows invoke --workflow-ids wf_abc123

# Invoke and wait with a 5-minute timeout
getlark workflows invoke --workflow-ids wf_abc123 --wait --timeout 300

# Invoke all workflows and wait with verbose logs
getlark workflows invoke --all --wait --verbose

# Check execution status
getlark workflows executions get wf_abc123 exec_xyz789

# Fetch execution logs
getlark workflows executions logs wf_abc123 exec_xyz789

# Cancel a running execution
getlark workflows executions cancel wf_abc123 exec_xyz789

# Trigger a repair
getlark workflows repairs trigger wf_abc123

# List repairs
getlark workflows repairs list wf_abc123

# Cancel a generation
getlark workflows generations cancel wf_abc123 gen_xyz789

# List events
getlark workflows events list wf_abc123

# Create a workflow group
getlark workflow-groups create --name "Checkout Flow"

# List workflow groups
getlark workflow-groups list

# Delete a workflow group
getlark workflow-groups delete grp_abc123

# Override API key inline
getlark --api-key sk-test-key workflows invoke --workflow-ids wf_abc123

# Store credentials for a secret context
getlark secret-contexts create --context production --secret username=admin --secret password=s3cret

# Update a single key in a secret context
getlark secret-contexts update production --key password --value new-s3cret

# List all secret contexts
getlark secret-contexts list

# View the keys stored in a secret context
getlark secret-contexts get production

# Delete a key from a secret context
getlark secret-contexts delete-key production password

# Delete a secret context
getlark secret-contexts delete production
```

## CI pipeline usage

The `--wait` flag makes the CLI well-suited for CI pipelines. The command blocks until every workflow finishes and exits with a non-zero code on failure.

For full CI setup instructions, see [CI integration](/ci).


# Executions
Source: https://docs.getlark.ai/executions

Execution statuses, artifacts, and suggested workflows.

## Execution statuses

Each workflow run moves through these statuses:

| Status      | Meaning                                   |
| ----------- | ----------------------------------------- |
| `pending`   | Queued, waiting to start.                 |
| `running`   | The agent is performing the test.         |
| `success`   | The test passed.                          |
| `failure`   | The test failed.                          |
| `cancelled` | You cancelled the run before it finished. |

Deterministic failures trigger a [summarization](/workflow-lifecycle#summarization) step. Lark classifies the failure as a script issue (auto-repair) or a product regression (alert via Slack/Linear). AI-driven executions skip this step.

Check an execution's status in the [dashboard](https://dashboard.getlark.ai/workflows) or through the API:

```bash theme={null}
curl https://api.getlark.ai/workflows/wf_abc123/executions/exec_xyz789 \
  -H "X-API-Key: $GETLARK_API_KEY"
```

## Artifacts

Each execution can produce artifacts: files the agent captured or generated during the test. You can download them from the [dashboard](https://dashboard.getlark.ai/workflows) or through the API.

<img alt="Screenshot showing the artifacts in the execution detail page in dashboard." />

### Artifact types

| Type          | Description                                  |
| ------------- | -------------------------------------------- |
| `screenshot`  | A screenshot the agent took during the test. |
| `video`       | A recording of the full test session.        |
| `javascript`  | JavaScript code the agent executed.          |
| `python`      | Python code the agent executed.              |
| `shellscript` | Shell commands the agent ran.                |

### Accessing artifacts (API)

Artifacts appear in the execution response under the `artifacts` array. Each entry includes:

* `artifact_type` - One of the types above.
* `filename` - The file name.
* `presigned_url` - A download URL.
* `presigned_url_expires_at` - When the URL stops working.

```json theme={null}
{
  "artifacts": [
    {
      "artifact_type": "screenshot",
      "filename": "login-page.png",
      "presigned_url": "https://...",
      "presigned_url_expires_at": "2026-03-25T12:00:00Z"
    }
  ]
}
```


# GitHub integration
Source: https://docs.getlark.ai/github

Investigate GitHub issues and propose end-to-end tests on pull requests.

Connect Lark to GitHub to do two things from your repos:

* **Investigate issues** — Comment `/investigate` on a GitHub issue and Lark posts a structured investigation report back on the thread.
* **Propose tests on PRs** — Add `.github/workflows/lark.yml` so Lark can propose new end-to-end tests when pull requests open.

## Setup

1. Open **Settings → Integrations** in the [dashboard](https://dashboard.getlark.ai/settings/integrations).
2. Click **Connect** on the GitHub card.
3. Install the Lark GitHub App and choose which repositories Lark can access.
4. After install, open **Configure → Manage repos** to add `.github/workflows/lark.yml` to each repo you want test proposals on.

### Add `lark.yml` to a repo

On the **Finish GitHub setup** page, click **Add lark.yml** for a repo. GitHub opens with the workflow file prefilled — review and commit it in your browser.

Each repo also needs an `ANTHROPIC_API_KEY` secret under **Settings → Secrets and variables → Actions**. Lark uses your key, so token spend goes to your Anthropic account. You can add the secret before or after committing the workflow file; the action skips with a friendly comment until the secret is set.

Repos show as **Connected** automatically after the first pull request triggers the workflow.

## Investigate issues

On any connected repository, a user with write access (owner, member, or collaborator) can comment:

```
/investigate
```

Lark reads the issue title, body, labels, and comment thread, runs an investigation, and posts the report back as a GitHub comment. While the investigation runs, Lark adds a `lark:investigating` label; when it finishes, that label is replaced with `lark:investigated` or `lark:investigation-failed`.

<Note>
  `/investigate` works on issues only, not pull requests. Comments from first-time or untrusted contributors are ignored.
</Note>

If `/investigate` is posted again while an investigation is already running for that issue, Lark skips the duplicate.

## Propose tests on pull requests

When `.github/workflows/lark.yml` is present, Lark runs on pull requests that are **opened** or **reopened**. It analyzes the diff and can propose new end-to-end tests for the changes.

Pull requests from forks are skipped — forked workflows cannot mint OIDC tokens with Lark's trusted audience.

## Reconfiguring or disconnecting

Click **Configure** on the GitHub card to review connected repos or open **Manage repos** to add `lark.yml` to more repositories.

Click **Disconnect** to remove the Lark GitHub App installation from your account. Lark stops responding to `/investigate` and test proposals stop running; existing GitHub comments and workflow files in your repos are left untouched.


# Introduction
Source: https://docs.getlark.ai/introduction



Lark lets you ship every commit with confidence. Write tests in plain English, run them on every PR or deploy, and know in minutes if something broke.

<CardGroup>
  <Card title="Quickstart" icon="rocket" href="/quickstart">
    Create your first workflow and run it from the dashboard or CI.
  </Card>

  <Card title="MCP" icon="plug" href="/mcp-quickstart">
    Connect AI coding agents like Claude Code and Cursor to Lark workflows via MCP.
  </Card>
</CardGroup>

## Why Lark

**Write tests in minutes.** Skip writing e2e scripts and managing test infra. Lark handles it. Describe what you want to test and you’re done in under two minutes. Choose deterministic runs or fully AI-driven flows.

**Tests adapt as your product evolves.** When you revamp your UI or change an API, tests don’t break on selectors or brittle code. Lark adapts and alerts you to the change instead.

**Test everything.** Lark’s agents can test anything a human could: UIs, APIs, SDKs, and async workflows, all in one place.

**Catch bugs before your users do.** Run tests on every commit, pull request, or deployment. Get instant alerts with detailed logs and screenshots when something fails.

## Need help?

<CardGroup>
  <Card title="Join our Slack" icon="slack" href="https://join.slack.com/t/larkcommunity/shared_invite/zt-3wqmfghs7-Rjbd74jt_bLac534lFwIQw">
    Ask questions and connect with other Lark users.
  </Card>

  <Card title="Contact us" icon="envelope" href="mailto:team@getlark.ai">
    For account or billing issues.
  </Card>
</CardGroup>


# Linear integration
Source: https://docs.getlark.ai/linear

Create Linear issues when a workflow uncovers a real product regression.

Lark can file a Linear issue when a deterministic workflow fails because of a bug in your product. Flaky scripts and infra hiccups do not file issues. Only failures classified as a real product regression do.

## Setup

1. Open **Settings → Integrations** in the [dashboard](https://dashboard.getlark.ai/settings/integrations).
2. Click **Connect** on the Linear card.
3. Authorize Lark in Linear. Lark requests `issues:create` and `comments:create` scopes.
4. Back in the dashboard, click **Configure**, pick the **default team** the issues should land in, and toggle **Issue creation** on.
5. Save.

## Triggers

Lark files a Linear issue in two cases:

| Trigger                    | When it fires                                                                                                                                                                        |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Workflow execution failure | A deterministic workflow fails and Lark's [summarization](/workflow-lifecycle#summarization) classifies the failure as `app_issue` (a real product regression, not a broken script). |
| Repair failure             | A deterministic workflow's repair attempt fails, indicating Lark could not get the test passing again.                                                                               |

Issues land in the default team's backlog. The title is `Workflow Failed: <workflow name>` (or `Workflow Repair Failed: <workflow name>`), and the body includes the failure summary plus a link back to the dashboard.

## Reconfiguring or disconnecting

Click **Configure** on the Linear card to change the default team or pause issue creation without disconnecting.

Click **Disconnect** to revoke Lark's access. Lark stops creating issues; existing issues stay in Linear untouched.


# MCP
Source: https://docs.getlark.ai/mcp-quickstart

Connect AI agents to Lark workflows with the Model Context Protocol.

Lark exposes a remote MCP server at:

```text theme={null}
https://api.getlark.ai/mcp?api_key=<API_KEY>
```

It provides tools for managing workflows, templates, groups, secret contexts, webhooks, and metrics. It covers the same surface as the [CLI](/cli).

## Authentication

Create a Lark API key from [Settings > API Keys](https://dashboard.getlark.ai/settings/api-keys).

## Integrations

### Claude (web and desktop)

Claude.ai and the Claude desktop app support remote MCP servers as **custom connectors**.

1. Open **Customize → Connectors → Add custom connector**.
2. Name it `Lark`.
3. Set the Remote MCP URL to `https://api.getlark.ai/mcp?api_key=<API_KEY>`.
4. Save.

Open a new chat and ask the agent to list your lark workflows to verify the connection.

### Cursor

Open **Cursor Settings → MCP → Add new MCP server**, or edit `~/.cursor/mcp.json` directly:

```json theme={null}
{
  "mcpServers": {
    "lark": {
      "type": "http",
      "url": "https://api.getlark.ai/mcp",
      "headers": {
        "X-API-Key": "<API_KEY>"
      }
    }
  }
}
```

Restart Cursor and Lark tools will be available to the agent. Open a new chat and ask the agent to list your lark workflows to verify the connection.

### Claude Code

<Info>
  For slash commands and branch-validation hooks, see [Skills](/skills).
</Info>

Add Lark as a remote HTTP MCP server:

```bash theme={null}
claude mcp add --transport http lark https://api.getlark.ai/mcp \
  --header "X-API-Key: <API_KEY>"
```

Or commit a project-local `.mcp.json` that reads the key from each user's environment:

```json theme={null}
{
  "mcpServers": {
    "lark": {
      "type": "http",
      "url": "https://api.getlark.ai/mcp",
      "headers": {
        "X-API-Key": "<API_KEY>"
      }
    }
  }
}
```

## Helpful prompts

Once the Lark MCP server is connected, copy any of these prompts and paste them into your agent to get started quickly.

### Set up Lark tests in bulk

````text title="Set up a suite of tests" expandable theme={null}
Follow the instructions below to create a bunch of e2e tests in Lark:


------------------------- Instructions -------------------------

## Goal

Lark (getlark.ai) is an end-to-end testing platform. We will bulk-import workflows into getlark by collaborating with the user to understand their product area, generating comprehensive test cases, and importing them as a job through the configured lark MCP. This can be useful for onboarding (going from zero to full coverage) or expanding test coverage for a specific product surface.

getlark workflows can test any surface — web UIs, HTTP/GraphQL APIs, CLIs, shell scripts, data pipelines, or mixed flows. Do not assume the target is a browser URL unless the user says so.

## Prerequisites

1. Ensure that the lark MCP is configured so you can interact with the getlark API through it. If it isn't, ask the user to follow the instructions at https://docs.getlark.ai/mcp-quickstart to set it up. If the MCP is configured, list its available tools and perform a simple list-workflows action to verify it is working before proceeding. All getlark operations in this prompt MUST go through the configured lark MCP. Do not shell out to a CLI. Discover the appropriate tool names by inspecting the MCP.
2. Ask the user about what product area they want to generate tests for in Lark. This will typically be something like their API, dashboard, or something similar. They will give you relevant information and links for it (like API docs url, dashboard url, etc). 

## Procedure

### Step 1 — Understand the product area

Gather any additional information you need about the product area to build a good understanding about it. These could include things like:

- **What is the product/feature?** (e.g., "our checkout flow", "the user management API", "the CLI tool for data imports")
- **What is the target?** (URL, API base, CLI binary, script path, etc.)
- **Are there specific user journeys or critical paths to cover?**
- **Are there credentials or secret contexts needed?** If yes, confirm they exist by listing secret contexts through the lark MCP.

If the user invoked the skill with a description already, use that as the starting point and ask only clarifying questions for gaps. 

Once you have a good understanding of the product to test, move on to next step.

### Step 2 — Assess existing coverage

Before generating new test cases, list all existing workflows through the lark MCP to understand what coverage already exists. Use a page size of 100 and paginate until all workflows have been retrieved.

Summarize the existing coverage for the user:

- Group workflows by feature area or theme (infer from names/descriptions)
- Highlight which areas of the product already have tests
- Identify gaps — areas the user mentioned in Step 1 that have no existing workflows

This prevents duplicate coverage and helps focus the new test cases on genuine gaps. If the user's target product area is already well-covered, let them know and ask whether they want to supplement with edge cases or shift focus to a different area.

### Step 3 — Research and generate test cases

**Aim for solid coverage.** The goal of bulk import is to seed broad, useful coverage — distinct user flows, important edge cases, and likely failure modes. Between AI driven and deterministic test, prefer the latter when possible since they are cheap and faster. 

Based on the product area and the coverage gaps identified in Step 2, develop a well-rounded set of test cases. Think about:

- **Happy paths** — core user journeys that must always work (login, checkout, CRUD operations, etc.)
- **Alternate user flows** — different roles, plan tiers, entry points, devices, or paths to the same outcome
- **Edge cases** — boundary conditions, empty states, max-length inputs, concurrent actions, special characters
- **Error handling** — invalid inputs, unauthorized access, network failures, graceful degradation
- **Cross-feature interactions** — flows that span multiple features or services
- **Regression-prone areas** — features that break often or have complex dependencies

For each test case, write a clear, actionable description about what to test. The description is what the AI agent reads at runtime to perform the test. You don't need to be too explicit with instructions (like specifying exact API request to make, etc). You can describe the user flow you want to test and Lark systems will implement the test appropriately.

**Choosing mode**: Prefer `deterministic` when possible — deterministic tests are cheaper and faster to run. Use `ai_driven` only when the test requires adaptive behavior (e.g., dynamic content, unpredictable UI states, flows that change frequently). A good default split is mostly deterministic with a handful of ai_driven tests for flows where flexibility is genuinely needed.

**Organizing with groups**: Use workflow groups to keep the new tests organized by product area or feature. List existing groups through the lark MCP. If a relevant group already exists, assign the new workflows to it using `group_id`. If none fits, ask the user about creating new group(s) (e.g., "Checkout Flow", "User Management API") through the lark MCP and use its ID in the import file. Well-organized groups make it easy to invoke all related tests together and keep the dashboard navigable as coverage grows. Grouping tests together by a logical domain is usually a nice approach (as opposed to putting all in a single broad group like API or dashboard).

### Step 4 — Write the import JSON file

Create a JSON file (default: `workflows-import.json` in the current working directory) that follows the `workflow_import` schema:

```json
{
  "workflows": [
    {
      "name": "Descriptive Test Name",
      "description": "Go to <target>, perform <action 1>, then <action 2>, assert <expected outcome>.",
      "mode": "ai_driven",
      "secret_contexts": ["context-name"],
      "group_id": "wgrp_..."
    }
  ]
}
```

Schema rules:
- `name` (string, required) — concise, Title-Case name (3–8 words) capturing the test intent.
- `description` (string, required) — full natural-language test steps. Include the target, actions, and assertions. This is what the AI agent uses to execute the test.
- `mode` (required) — `"deterministic"` (locked to generated script, cheaper and faster) or `"ai_driven"` (tolerates minor UI changes, more flexible). Prefer `deterministic` where possible; use `ai_driven` only for flows that genuinely need adaptive behavior.
- `secret_contexts` (array of strings or null, optional) — names of secret contexts the workflow needs for auth/tokens.
- `group_id` (string or null, optional) — workflow group ID to assign the workflow to.

No additional properties are accepted.

### Step 5 — Review and iterate with the user

Present the generated test cases to the user in a readable format (table or numbered list showing name + summary of what each test covers). Ask them to review and suggest changes:

- Are there missing test cases?
- Should any be removed or merged?
- Are descriptions accurate and detailed enough?
- Are the right secret contexts and groups assigned?

Iterate on the JSON file based on feedback. Continue until the user confirms the test cases are ready for import. Do not create the import job without explicit user approval.

### Step 6 — Create the import job

Once the user approves, create the import job through the lark MCP, passing:
- a descriptive `name` for the job (e.g., "Import Checkout Flow Tests" or "Onboarding - User Management API Coverage")
- the `workflows` array from `./workflows-import.json` inline as the job input

The create-job tool validates the payload server-side and will NOT create a job if it is invalid — it returns the validation errors instead. If it returns errors, read them, fix the JSON file accordingly, and call it again (no job is created on a failed attempt, so retrying after a fix is safe). Common issues:
- Missing required fields (`name`, `description`, `mode`)
- Invalid `mode` value (must be exactly `"ai_driven"` or `"deterministic"`)
- Empty `workflows` array
- Extra properties not in the schema
- Non-unique or empty strings

Once it succeeds it returns the created job resource (with a job `id`) — do not call it again for the same payload.

### Step 7 — Report result

The create-job tool returns the job resource as JSON. Extract and report:

- Job `id`
- Job `status` (typically `pending` or `running` initially)
- **Dashboard URL**: `https://dashboard.getlark.ai/jobs/<id>`

Tell the user the workflow import job was created successfully and share the dashboard URL. Let them know they can:
- Track progress on the dashboard
- Check job status through the lark MCP with the job ID
- Cancel if needed through the lark MCP with the job ID

## Guidelines for writing good test descriptions

- Start with the target (URL, API endpoint, CLI command, etc.)
- Use imperative verbs: "Go to", "Click", "Submit", "Assert", "Verify", "Enter", "Wait for"
- End with a clear assertion of expected outcome
- Reference credentials by secret context name, never hardcode secrets in descriptions
- Keep each workflow focused on one logical user journey — don't cram multiple unrelated flows into a single workflow
- Be specific enough that someone unfamiliar with the product can follow the steps

## Example

User says: "I want to add test coverage for our e-commerce checkout flow at https://shop.example.com"

After research and iteration, produce:

```json
{
  "workflows": [
    {
      "name": "Guest Checkout Happy Path",
      "description": "Go to https://shop.example.com/products, add the first available product to cart, proceed to checkout as a guest, fill shipping with valid US address, select standard shipping, enter test card 4242424242424242, submit order, assert order confirmation page shows order number.",
      "mode": "ai_driven",
      "secret_contexts": ["staging"]
    },
    {
      "name": "Empty Cart Checkout Guard",
      "description": "Go to https://shop.example.com/cart with an empty cart, attempt to click Proceed to Checkout, assert the checkout button is disabled or a message says 'Your cart is empty'.",
      "mode": "ai_driven"
    },
    {
      "name": "Apply Discount Code",
      "description": "Go to https://shop.example.com/products, add any product to cart, go to cart, enter discount code SAVE10 in the promo field, click Apply, assert the total decreases and a 'Discount applied' message is shown.",
      "mode": "ai_driven",
      "secret_contexts": ["staging"]
    },
    {
      "name": "Invalid Payment Card Rejected",
      "description": "Go to https://shop.example.com/products, add a product to cart, proceed to checkout as guest, fill valid shipping, enter invalid card number 1234567890123456, submit payment, assert an error message about invalid card is displayed and order is not placed.",
      "mode": "ai_driven",
      "secret_contexts": ["staging"]
    }
  ]
}
```

Then create the import job through the lark MCP with the name "Import Checkout Flow Tests", passing the `workflows` array inline.

Report the dashboard URL to the user.

## Failure modes

- **Validation errors**: The create-job tool returns the errors without creating a job. Fix the JSON and call it again.
- **Auth errors**: The lark MCP is likely not authenticated or not configured correctly. Ask the user to revisit https://docs.getlark.ai/mcp-quickstart to confirm the MCP setup.
- **Unknown secret context**: Verify by listing secret contexts through the lark MCP before including in the file.
- **Unknown group ID**: Verify by listing workflow groups through the lark MCP before including in the file.

## Do NOT

- Do not shell out to a `getlark` CLI. All getlark operations must go through the configured lark MCP.
- Do not create the import job through the lark MCP more than once for the same payload. Each call creates a separate job — calling it twice will import the workflows twice, resulting in duplicates. If the job was created successfully (returned a job ID and dashboard URL), do not retry it.
- Do not create the import job without user approval of the test cases.
- Do not hardcode secrets or API keys in workflow descriptions. Use secret contexts.
- Do not create excessively vague descriptions. Each must be actionable by an AI agent at runtime.
- Do not invent secret context names or group IDs — verify they exist first via the lark MCP.
````


# Preview deployments
Source: https://docs.getlark.ai/preview-deployments

Get a publicly accessible version of your app for every pull request.

## What is a preview deployment?

<img alt="Screenshot how preview deployments work." />

A preview deployment is a publicly accessible, per-branch environment for any Docker Compose project. For every pull request, Lark spins up a fully functional version of your app — similar to your local environment — at a URL like `mybranch.preview.example.com`.

This is a managed version of our open source project [Preview Use](https://github.com/getlark/previewuse).

Preview deployments are useful for:

* **Assisting with code reviews** — play around with the change and validate side effects directly instead of going deep on the diff.
* **Verifying the work of background agents** — confirm an agent's change behaves as expected in a live environment.

<Note>Preview deployments must be enabled for your account. The integration is free and we don't plan to monetize it. [Contact us](mailto:team@uselark.io) if you'd like access.</Note>

## Triggering a preview deployment

Once enabled on a connected repository, you can create a preview deployment for any branch in one of two ways:

* Add a configured label (like `deploy-preview`) to the pull request.
* Comment the configured command (like `/lark-deploy-preview`) on the pull request.

You'll get back a URL (like `mybranch.preview.example.com`) with a fully functional app.

## Test data setup

We support test data setup via scripts that you write, so you don't have to set up accounts and test data from scratch in the preview environment. Your scripts run as part of bringing the environment up, leaving you with a ready-to-use app.


# QA reports
Source: https://docs.getlark.ai/qa-reports

Run an AI-driven QA audit of your product and get a structured report of issues.

## What is a QA report?

A QA report is an automated, end-to-end audit of your product. Instead of testing a single flow like a [workflow](/workflow-lifecycle), a QA report covers your entire product surface:

1. Lark's agent analyzes your product and identifies areas to test.
2. It tests each area one by one, logging issues it finds.
3. When testing is complete, it writes a summary with all issues ranked by priority.

This is useful when you want broad coverage fast — before a big release, as a periodic health check, etc.

<Note>QA reports must be enabled for your account. [Contact us](mailto:team@uselark.io) if you don't see the option in your dashboard.</Note>

## Creating a QA report

<img alt="Screenshot showing how to create a QA report in dashboard." />

<Steps>
  <Step title="Open the QA Reports page">
    In the [dashboard](https://dashboard.getlark.ai/qa-reports), go to **QA Reports**. Click **Create report**.
  </Step>

  <Step title="Enter your product name">
    Give the report a product name (e.g. "Acme Dashboard").
  </Step>

  <Step title="Provide relevant information">
    Add additional information like relevant links (developer documentation url,  dashboard url, etc). You can also tell the agent what to focus on or what to skip.
  </Step>

  <Step title="Attach secrets if needed">
    If the product requires credentials to test (login details, API keys, etc.), attach one or more [secret contexts](/secrets). The agent uses these to authenticate during testing.
  </Step>

  <Step title="Submit">
    Click **Create**. Lark begins analyzing your product to identify testing areas.
  </Step>
</Steps>

## QA report lifecycle

Once created, a report goes through three phases:

1. **Identification** — The agent analyzes your product and proposes areas to test. When it finishes, the report pauses so you can review the proposed areas.
2. **Testing** — Click **Trigger testing** to start. The agent works through each area one at a time. You can pause and resume testing at any point.
3. **Complete** — All areas have been tested and a summary is generated.

## Test areas and issues

Each area the agent tests produces a test report containing:

* **Result** — Whether the area passed or failed.
* **Notes** — What the agent observed.
* **Issues** — A list of problems found, each with a title, description, priority, and type.

## Summary and reproducible tests

Once all areas are tested, Lark writes a summary of the findings. The summary is written for PMs and engineers: it highlights what passed, what failed, and what needs attention.

If the agent produced scripts to reproduce any of the issues it found, a **reproduction package** is available for download. This is a zip file containing test scripts and a readme that tell you how to run tests locally to verify the reported issues.


# Quickstart
Source: https://docs.getlark.ai/quickstart

Create and run your first workflow in minutes from the dashboard or CLI.

Prefer to run Lark from an AI coding agent? See [MCP](/mcp-quickstart) for Claude Code, Cursor, and other agent integrations.

## Create your first workflow

<Tabs>
  <Tab title="Dashboard">
    <img alt="Screenshot showing how to create a testing workflow in dashboard." />

    <Steps>
      <Step title="Open the workflows page">
        In the [dashboard](https://dashboard.getlark.ai/workflows), go to **Workflows**. Click **Create workflow** to add a new one.
      </Step>

      <Step title="Describe what you want to test">
        Write your test in plain English. For example, "Log in and verify the dashboard loads" or "Call the API and check the response." No code required.
      </Step>

      <Step title="Choose how the workflow runs">
        * **Deterministic (i.e. scripted)** - The AI writes a script that runs the same steps every time. Lark keeps the test updated as your product changes (e.g. UI updates).
        * **AI-driven** - The AI performs the test from scratch each run, deciding how to achieve the goal. Best for complex flows like "follow the integration quickstart and verify it works."
      </Step>

      <Step title="Add secrets if needed">
        If the test needs credentials (API keys, login credentials, etc.), attach a [secret context](/testing/secrets). Otherwise you can skip this.
      </Step>

      <Step title="Run the workflow">
        Hit **Run**. The workflow runs in a sandbox environment. When it finishes, you'll see the result and any artifacts (screenshots, videos, logs).
      </Step>
    </Steps>
  </Tab>

  <Tab title="CLI">
    Make sure you have Node.js 18+ and your API key set:

    ```bash theme={null}
    export GETLARK_API_KEY=your-api-key
    ```

    <Steps>
      <Step title="Create a workflow">
        ```bash theme={null}
        npx -y @getlark/cli workflows create \
          --name "New User Signup" \
          --description "Go to dashboard url and verify that you can sign up as a new user." \
          --mode deterministic
        ```

        Pick a name, describe what to test in plain English, and choose a mode:

        * **Deterministic** — The AI writes a script that runs the same steps every time. Lark keeps the test updated as your product changes (e.g. UI updates).
        * **AI-driven** (default) — The AI performs the test from scratch each run, deciding how to achieve the goal. Best for complex flows.

        See the [CLI reference](/testing/cli) for all options.
      </Step>

      <Step title="Add secrets if needed">
        If the test needs credentials, create a [secret context](/testing/secrets) in the dashboard and attach it with `--secret-contexts`:

        ```bash theme={null}
        npx -y @getlark/cli workflows create \
          --name "User Login" \
          --description "Go to the dashboard and verify you can login to the dashboard." \
          --mode deterministic \
          --secret-contexts dashboard_login
        ```
      </Step>

      <Step title="Run the workflow">
        ```bash theme={null}
        npx -y @getlark/cli workflows invoke --all --wait
        ```

        The `--wait` flag blocks until the run finishes. When it completes you'll see the result in your terminal.
      </Step>
    </Steps>
  </Tab>
</Tabs>

## View results

After the run completes, open it in the dashboard to see:

* **Summary** - Pass/fail and high-level outcome
* **Steps** - What the agent did (and, for AI-driven runs, how it chose to do it)
* **Logs** - Detailed agent output
* **Artifacts** - Screenshots, recordings, and other generated files

<img alt="Screenshot showing the result of a workflow execution in dashboard." />

Next, run the same workflow [from CI](/testing/ci) so it runs on every PR or deploy, or drive workflows directly via [MCP](/mcp-quickstart) from Claude Code, Cursor, and other agents.


# Repairs and regeneration
Source: https://docs.getlark.ai/repairs-and-regeneration

How Lark fixes and rebuilds deterministic workflow scripts.

Repairs and regeneration apply to **scripted workflows only**. AI-driven workflows have no stored script to fix or rebuild.

## Repair

A repair fixes a scripted workflow's test script when it breaks. This happens when your product changes in a way the existing script can't handle (a renamed element, a changed flow, a new step).

### Auto-repair

Lark can repair workflows on its own. After a scripted workflow's execution fails, Lark first runs [summarization](/workflow-lifecycle#summarization) to decide whether the script is at fault. If the failure is classified as a `test_issue` and auto-repair is enabled for your account, Lark kicks off a repair. Failures classified as `app_issue` (real product regressions) leave the workflow `active` and skip the repair.

Auto-repair is an account-level setting. You can enable or disable it in the [dashboard](https://dashboard.getlark.ai/settings/workflows).

### Manual repair

Trigger a repair from the dashboard or the API:

Navigate to the workflow in the [dashboard](https://dashboard.getlark.ai/workflows) and click **Repair**.

Or trigger a repair through the API:

```bash theme={null}
curl -X POST https://api.getlark.ai/workflows/wf_abc123/repair \
  -H "X-API-Key: $GETLARK_API_KEY"
```

## Regeneration

You can also regenerate a scripted workflow if you materially change the purpose of the test.

Navigate to the workflow in the [dashboard](https://dashboard.getlark.ai/workflows) and click **Regenerate** under the `⋮` menu.

```bash theme={null}
curl -X POST https://api.getlark.ai/workflows/wf_abc123/regenerate \
  -H "X-API-Key: $GETLARK_API_KEY"
```

## Repair vs. regeneration

|                              | Repair                        | Regeneration                     |
| ---------------------------- | ----------------------------- | -------------------------------- |
| **Does what**                | Patches the existing script   | Rebuilds the script from scratch |
| **Use when**                 | A small change broke the test | The test needs a full rewrite    |
| **Can be automatic**         | Yes (auto-repair)             | No, manual only                  |
| **Preserves existing logic** | Yes, changes only what broke  | No, starts fresh                 |


# Scheduled runs
Source: https://docs.getlark.ai/scheduling

Run workflows on a recurring schedule.

## Setting a schedule

You can schedule any workflow to run on a recurring basis from the [dashboard](https://dashboard.getlark.ai/workflows) or API.

<img alt="Screenshot showing the schedule editor in dashboard." />

You can also update the schedule through the API:

```bash theme={null}
curl -X PUT https://api.getlark.ai/workflows/wf_abc123 \
  -H "X-API-Key: $GETLARK_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"schedule": "0 9 * * *"}'
```

Learn more about configuring alerts in [Slack](/slack).


# Managing secrets
Source: https://docs.getlark.ai/secrets

Store credentials securely and pass them to workflows via secret contexts.

## What’s a secret context?

A secret context is a set of key-value pairs.

* The **key** is the name your workflow uses (e.g. `api_key`, `login_username`, `login_password`).
* The **value** is the secret itself.

Create and edit contexts in the [Secrets section](https://dashboard.getlark.ai/settings/secrets) of the dashboard, then attach one or more to a workflow when you create or edit it (see [Quickstart](/guides/quickstart)).

<img alt="Screenshot showing how to create secret contexts in dashboard." />

<Note>Secrets are encrypted at rest and never stored in plain text. During a run they're only available inside an isolated sandbox, which is wiped when the run finishes. They're never logged.</Note>


# Skills
Source: https://docs.getlark.ai/skills

Install Lark skills for Claude Code, Cursor, and other Skills-compatible agents.

Agent Skills are modular capabilities that extend AI agents with domain-specific expertise. The Lark skills teach Claude Code — and any other agent in the Skills ecosystem — how to author, invoke, and manage end-to-end test [workflows](/workflow-lifecycle) via the [`getlark` CLI](/cli).

The [Lark plugin for Claude Code](https://github.com/getlark/skills) bundles the same six skills **plus** `/getlark:*` slash commands and an optional hook that validates your feature branch automatically after every `git commit` or `git push`.

<Info>
  Skills work by providing structured guidance to AI agents, enabling them to drive Lark through natural-language commands without being primed each session.
</Info>

## Key features

<CardGroup>
  <Card title="Author tests from descriptions" icon="wand-magic-sparkles">
    Turn a natural-language description (target URL + steps) into a workflow. The `create-workflow` skill auto-generates the name.
  </Card>

  <Card title="Validate feature branches" icon="code-branch">
    Run workflows against the work-in-progress on your current branch before opening a PR.
  </Card>

  <Card title="Debug failing runs" icon="bug">
    Pull execution logs, repair history, and event streams from the terminal — no context switch to the dashboard.
  </Card>

  <Card title="Manage test infrastructure" icon="list">
    List, update, and archive workflows, workflow groups, secret contexts, executions, repairs, generations, and events.
  </Card>

  <Card title="Background knowledge" icon="book">
    The `getlark-overview` skill auto-loads whenever you mention Lark, so suggestions are accurate without being primed.
  </Card>

  <Card title="Branch-validation hook" icon="shield-check">
    Opt-in `PostToolUse` hook runs your configured workflows after `git commit` or `git push` and reports pass/fail to Claude.
  </Card>
</CardGroup>

## Installation

<Tabs>
  <Tab title="Claude Code plugin">
    Installs the skills **plus** `/getlark:*` slash commands and the optional branch-validation hook.

    <Steps>
      <Step title="Add the marketplace">
        ```
        /plugin marketplace add getlark/skills
        ```
      </Step>

      <Step title="Install the plugin">
        ```
        /plugin install getlark
        ```
      </Step>

      <Step title="Reload plugins">
        ```
        /reload-plugins
        ```
      </Step>

      <Step title="Run setup">
        ```
        /getlark:setup
        ```

        The `setup` skill installs `@getlark/cli`, walks you through creating an API key, and persists `GETLARK_API_KEY` to your shell rc.
      </Step>
    </Steps>
  </Tab>

  <Tab title="Vercel Skills CLI">
    The [Vercel Skills CLI](https://github.com/vercel-labs/skills) installs just the skills (no slash commands or hooks) and works with Claude Code, Cursor, Codex, OpenCode, Windsurf, Gemini CLI, Copilot, and more.

    <Steps>
      <Step title="Install the skills">
        ```bash theme={null}
        npx skills add getlark/skills
        ```

        The CLI detects your agent and drops the skills in the right place (Claude `SKILL.md`, Cursor rules, `AGENTS.md`, etc.).
      </Step>

      <Step title="Run setup">
        Ask your agent to run the `setup` skill. It installs `@getlark/cli`, helps you create an API key at the [dashboard](https://dashboard.getlark.ai/settings/api-keys), and persists `GETLARK_API_KEY` to your shell rc.
      </Step>
    </Steps>
  </Tab>
</Tabs>

<Check>
  Verify the install by running `getlark workflows list --limit 1` from your shell.
</Check>

## Included skills

| Skill              | What it does                                                                                                                                               |
| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `getlark-overview` | Background on Lark concepts (workflows, groups, executions, repairs, generations, secret contexts, events). Auto-loads when you mention getlark or larkci. |
| `setup`            | Installs `@getlark/cli` and configures `GETLARK_API_KEY`.                                                                                                  |
| `create-workflow`  | Turns a natural-language test description into a `getlark workflows create` invocation.                                                                    |
| `invoke-workflow`  | Runs one or more workflows, waits for terminal status, reports pass/fail.                                                                                  |
| `validate-branch`  | Runs configured workflows against the current branch to check for regressions.                                                                             |
| `manage`           | Read/update/archive workflows, groups, secret contexts, executions, repairs, generations, and events.                                                      |

## Try it out

Once installed, you can drive Lark through natural-language commands.

### Author a new test from a description

```
Create a workflow that signs up a new user on https://app.example.com/signup and verifies the confirmation email appears.
```

Claude invokes `/getlark:create-workflow`, derives a name ("Signup Flow Confirmation"), and creates the workflow. You get the workflow ID and a dashboard link.

### Validate before shipping

```
Run the checkout workflows against this branch.
```

Claude invokes `/getlark:invoke-workflow --group-name "Checkout Flow" --wait` and reports the result.

### Debug a failing run

```
Why did wf_abc123 fail on its last run?
```

Claude uses `/getlark:manage` to fetch the execution details, steps, and artifacts, and explains what went wrong.

## Optional: automatic branch validation

The plugin ships an opt-in `PostToolUse` hook that runs your configured workflows after `git commit` or `git push`.

Enable it by creating `.claude/getlark.local.md` at the root of any project:

```yaml theme={null}
---
enabled: true
# Optional: restrict to specific workflows (default: run all)
workflow_ids: []
# Optional: restrict to a workflow group
workflow_group_id: ""
# Optional: poll timeout in seconds (default: 600)
poll_timeout_seconds: 600
---
```

When enabled, the hook runs your configured workflows and reports the result back to Claude. When the file is missing or `enabled: false`, the hook is a no-op.

<Warning>
  The hook runs real workflows against your deployed environment. Only enable it on projects where you intend to validate after every commit or push — and consider scoping `workflow_ids` or `workflow_group_id` for faster feedback.
</Warning>

## Environment variables

The plugin passes these through to the CLI unchanged:

| Variable          | Purpose      | Default                  |
| ----------------- | ------------ | ------------------------ |
| `GETLARK_API_KEY` | API key      | (required)               |
| `GETLARK_API_URL` | API base URL | `https://api.getlark.ai` |

## Further reading

<CardGroup>
  <Card title="CLI reference" icon="terminal" href="/cli">
    Every capability the skills expose, available directly via the `getlark` CLI.
  </Card>

  <Card title="Skills repository" icon="github" href="https://github.com/getlark/skills">
    View source, report issues, and contribute.
  </Card>
</CardGroup>


# Slack integration
Source: https://docs.getlark.ai/slack

Get workflow results posted to a Slack channel.

Lark can alert you when a workflow fails by posting to a Slack channel. Alerts fire for failures classified as a real product regression. Flaky scripts and infra hiccups stay quiet, filtered out by [summarization](/workflow-lifecycle#summarization).

## Setup

Connect Lark to Slack from the [dashboard](https://dashboard.getlark.ai/settings/integrations).

1. Go to **Settings > Integrations** in the dashboard.
2. Click **Connect Slack**.
3. Authorize Lark in the Slack authorization prompt and pick a channel.
4. Lark posts workflow results to that channel from now on.

## Updating the integration

To switch channels or reconfigure the integration, click the configuration link shown on the integrations page in the dashboard. This opens the Slack app settings where you can update the channel.


# Webhooks
Source: https://docs.getlark.ai/webhooks

Receive HTTP callbacks when workflow events happen in Lark.

A webhook posts a signed JSON payload to a URL you control whenever a workflow event fires. Use them to log results into your data warehouse or kick off downstream automation when a test passes or fails.

## Create a webhook

1. Open **Settings → Webhooks** in the [dashboard](https://dashboard.getlark.ai/settings).
2. Click **Add webhook**.
3. Enter the URL Lark should POST to and pick the events you want to receive.
4. Save. Lark shows the **signing secret** once. Copy it now and store it somewhere safe.

You can have up to 5 webhooks per account.

## Events

| Event                          | Fires when                                                        |
| ------------------------------ | ----------------------------------------------------------------- |
| `workflow_execution.success`   | A workflow execution finishes with status `success`.              |
| `workflow_execution.failure`   | A workflow execution finishes with status `failure`.              |
| `workflow_execution.cancelled` | A workflow execution is cancelled.                                |
| `workflow_generation.success`  | Lark finishes generating a deterministic workflow's script.       |
| `workflow_generation.failure`  | Generation could not produce a working script.                    |
| `workflow_repair.success`      | A repair fixed the script and the workflow is ready to run again. |
| `workflow_repair.failure`      | A repair attempt failed.                                          |

## Payload

Every payload uses the same envelope:

```json theme={null}
{
  "event": "workflow_execution.failure",
  "timestamp": "2026-05-01T12:34:56Z",
  "workflow": {
    "id": "wf_abc123",
    "name": "New User Signup",
    "description": "Go to dashboard url and verify that you can sign up as a new user.",
    "secret_context_names": ["dashboard_login"]
  },
  "data": {
    "execution_id": "exec_xyz789",
    "status": "failure",
    "summary": "The signup button did not respond after submission."
  }
}
```

The `data` block depends on the event type and includes the relevant runnable id (`execution_id`, `generation_id`, `repair_id`), its status, timing, and a short summary.

## Verifying signatures

Lark signs every request with HMAC-SHA256 over the raw request body, using your webhook's signing secret. The hex digest arrives in the `X-Lark-Signature` header. Reject requests whose computed signature doesn't match.

<CodeGroup>
  ```python Python theme={null}
  import hashlib
  import hmac

  def verify(body: bytes, signature: str, secret: str) -> bool:
      expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
      return hmac.compare_digest(expected, signature)
  ```

  ```javascript Node.js theme={null}
  import crypto from "node:crypto";

  function verify(body, signature, secret) {
    const expected = crypto
      .createHmac("sha256", secret)
      .update(body)
      .digest("hex");
    return crypto.timingSafeEqual(
      Buffer.from(expected),
      Buffer.from(signature),
    );
  }
  ```
</CodeGroup>

Pass the raw request body to `verify`, not a re-serialized object. Re-encoding can change byte ordering and break the signature check.

## Delivery and retries

* Lark expects a `2xx` response within 10 seconds.
* Failed deliveries (timeouts, non-2xx) retry up to 3 times with exponential backoff (10s, 20s, 40s).
* After 3 failed retries Lark drops the delivery and logs the error. The webhook stays active.

## Pausing or removing a webhook

Toggle **Active** off on the webhook row to pause delivery without losing the configuration. Click the trash icon to remove it.


# Workflow lifecycle
Source: https://docs.getlark.ai/workflow-lifecycle

Workflow modes, statuses, and how they change over time.

## Modes

Each workflow runs in one of two modes, chosen at creation time:

**Deterministic** - Lark's AI writes a test script based on your description. The script runs the same steps on each invocation. If your product changes, Lark repairs the script to match. Best for repeatable regression tests.

**AI-driven** - Lark's AI performs the test from scratch on each run, deciding how to reach the goal you described. No stored script. Best for exploratory tests and complex flows where the exact path may vary.

## Workflow statuses

A workflow moves through these statuses as Lark generates, runs, and maintains it:

| Status                  | Meaning                                                                                                   |
| ----------------------- | --------------------------------------------------------------------------------------------------------- |
| `pending_generation`    | A deterministic workflow has been created and is queued for script generation.                            |
| `generating`            | Lark is building the test script.                                                                         |
| `generation_successful` | Script generation finished. The workflow is ready to run.                                                 |
| `generation_failed`     | Lark could not produce a working script. Edit the description and retry.                                  |
| `active`                | The workflow is ready to run on invocation or schedule.                                                   |
| `pending_summary`       | A deterministic execution failed and is queued for [summarization](#summarization).                       |
| `summarizing`           | Lark is classifying the failure to decide whether to repair.                                              |
| `needs_repair`          | A deterministic workflow's script broke and needs a fix. See [repairs](/repairs-and-regeneration#repair). |
| `repairing`             | Lark is fixing the test script.                                                                           |
| `repair_successful`     | The repair finished. The workflow is ready to run again.                                                  |
| `repair_failed`         | The repair did not succeed. This likely indicates a bug in your product or environment.                   |
| `archived`              | The workflow is hidden and cannot run. Unarchive it to restore it.                                        |

## Summarization

When a deterministic workflow's execution fails, Lark runs a summarization step before deciding what to do next. Summarization classifies the failure as one of:

| Category     | Meaning                                                                                      | Next step                                                              |
| ------------ | -------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `test_issue` | The script is out of date with your product. Renamed elements, changed flows, missing steps. | Workflow moves to `needs_repair`. Auto-repair fires if enabled.        |
| `app_issue`  | The script ran fine and surfaced a real bug in your product.                                 | Workflow stays `active`. No repair runs. Slack and Linear alerts fire. |

This split keeps repairs targeted (only when the script is the problem) and stops alert noise from script drift. AI-driven workflows skip summarization. They have no stored script to be at fault.