CLI - Lark Documentation

The Lark 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:

npx -y @getlark/cli workflows invoke --all --wait

Or install globally:

npm install -g @getlark/cli

Authentication

The fastest way to authenticate is getlark login:

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:

--api-key flag
GETLARK_API_KEY environment variable
~/.getlark/config.json
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. Get your API key from the dashboard.

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

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

getlark workflows create \
  --name "checkout-flow" \
  --description "Test the full checkout process" \
  --mode deterministic \
  --secret-contexts production staging

Get workflow details

getlark workflows get <workflow_id>

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

Update a workflow

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

getlark workflows archive <workflow_id>

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

Unarchive a workflow

getlark workflows unarchive <workflow_id>

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

List workflows

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.

# 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

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

getlark workflows executions get <workflow_id> <execution_id>

Get execution logs

getlark workflows executions logs <workflow_id> <execution_id>

Cancel a running execution

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

getlark workflows repairs trigger <workflow_id>

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

List workflow repairs

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

getlark workflows repairs get <workflow_id> <repair_id>

Cancel a running repair

getlark workflows repairs cancel <workflow_id> <repair_id>

Get repair logs

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

getlark workflows generations cancel <workflow_id> <generation_id>

Workflow groups

Group related workflows together for organization and bulk filtering.

Create a workflow group

getlark workflow-groups create --name "Checkout Flow"

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

List workflow groups

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

getlark workflow-groups get <group_id>

Update a workflow group

getlark workflow-groups update <group_id> --name "Updated Name"

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

Delete a workflow group

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

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:

{
  "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"
    }
  ]
}

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

List jobs

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

getlark jobs get <job_id>

Cancel a job

getlark jobs cancel <job_id>

Cancels a pending or running job.

Upload a job from a file

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

getlark jobs validate --file ./workflows.json

Flag	Required	Description	Default
`--file <path>`	Yes	Path to the input file (same schema as `jobs create`)
`--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

getlark secret-contexts list

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

Get a secret context

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

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)

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

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

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

getlark secret-contexts delete-key <context> <key>

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

Examples

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

Documentation Index

​Installation

​Authentication

​Global options

​Workflows

​Create a workflow

​Get workflow details

​Update a workflow

​Archive a workflow

​Unarchive a workflow

​List workflows

​Invoke workflows

​Exit codes

​List workflow events

​Executions

​Get execution details

​Get execution logs

​Cancel a running execution

​Repairs

​Trigger a workflow repair

​List workflow repairs

​Get repair details

​Cancel a running repair

​Get repair logs

​Generations

​Cancel a running generation

​Workflow groups

​Create a workflow group

​List workflow groups

​Get a workflow group

​Update a workflow group

​Delete a workflow group

​Jobs

​Create a job from an inline JSON input file

​workflow_import input file schema

​List jobs

​Get a job

​Cancel a job

​Upload a job from a file

​Validate an input file without creating a job

​Secret contexts

​List secret contexts

​Get a secret context

​Create or replace a secret context

​Update a key in a secret context

​Delete a secret context

​Delete a key from a secret context

​Examples

​CI pipeline usage

Installation

Authentication

Global options

Workflows

Create a workflow

Get workflow details

Update a workflow

Archive a workflow

Unarchive a workflow

List workflows

Invoke workflows

Exit codes

List workflow events

Executions

Get execution details

Get execution logs

Cancel a running execution

Repairs

Trigger a workflow repair

List workflow repairs

Get repair details

Cancel a running repair

Get repair logs

Generations

Cancel a running generation

Workflow groups

Create a workflow group

List workflow groups

Get a workflow group

Update a workflow group

Delete a workflow group

Jobs

Create a job from an inline JSON input file

`workflow_import` input file schema

List jobs

Get a job

Cancel a job

Upload a job from a file

Validate an input file without creating a job

Secret contexts

List secret contexts

Get a secret context

Create or replace a secret context

Update a key in a secret context

Delete a secret context

Delete a key from a secret context

Examples

CI pipeline usage