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

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