---
title: "skillset test"
slug: "skillset/reference/cli/test"
description: The Skillset test command can run declared or ad hoc provider runtime tests.
---
<!-- Generated by `bun run docs:generate`; do not edit directly. -->

<a id="skillset-test"></a>

> Generated from Skillset's CLI presentation contract. See the [documentation system](https://github.com/outfitter-dev/skillset/blob/24800e02ed4e7150ea1bc7130c35603c98ea9da2/docs/development/documentation-system.md).

Run declared or ad hoc provider runtime tests.

## `skillset test`

Run declared or ad hoc provider runtime tests.

### Usage

```text
skillset test [name] [--json] [--root <path>]
skillset test --target <claude|codex|cursor> [--prompt <text>|--prompt-file <path>] [--plugin <id>] [--name <name>] [--timeout-ms <ms>] [--claude-setting-sources <isolated|user|project|local>] [--background] [--json] [--root <path>]
```

### Options

| Option | Meaning |
| --- | --- |
| `--background` | Queue an ad hoc test and return after recording it. |
| `--claude-setting-sources <value>` | Select Claude-native setting sources for an explicit Claude ad hoc test. |
| `--json` | Emit exactly one versioned finite JSON result document. |
| `--name <value>` | Set a route-specific human or stable name where the route permits it. |
| `--plugin <value>...` | Select plugins for an ad hoc test rendering. |
| `--prompt <value>` | Provide an inline ad hoc test prompt. |
| `--prompt-file <value>` | Provide a source-local ad hoc test prompt file. |
| `--root <value>` | Select the repository root; defaults to cwd or Git root according to the route. |
| `--target <value>` | Select one provider target for a route. |
| `--timeout-ms <value>` | Set the run timeout in milliseconds. |

## `skillset test list`

List retained runtime test runs.

### Usage

```text
skillset test list [--json] [--root <path>]
```

### Options

| Option | Meaning |
| --- | --- |
| `--json` | Emit exactly one versioned finite JSON result document. |
| `--root <value>` | Select the repository root; defaults to cwd or Git root according to the route. |

## `skillset test status`

Show runtime test progress and result state.

### Usage

```text
skillset test status [run-id] [--json] [--root <path>]
```

### Options

| Option | Meaning |
| --- | --- |
| `--json` | Emit exactly one versioned finite JSON result document. |
| `--root <value>` | Select the repository root; defaults to cwd or Git root according to the route. |

## `skillset test tail`

Tail retained runtime test output.

### Usage

```text
skillset test tail [run-id] [--lines <count>] [--json] [--root <path>]
```

### Options

| Option | Meaning |
| --- | --- |
| `--json` | Emit exactly one versioned finite JSON result document. |
| `--lines <value>` | Limit retained run output lines. |
| `--root <value>` | Select the repository root; defaults to cwd or Git root according to the route. |