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

# Managing experiments

> Use the Hivekit CLI to create, manage, and monitor Hive experiments from your terminal.

## Creating an experiment

```
hive create exp -c hive.yaml
```

The `-c` flag is required and points to the experiment config file. The experiment name is specified inside the YAML via the `experiment_name` field. Adding a `-` suffix to `experiment_name` appends a random unique ID — we recommend this to avoid name clashes.

You can override config values without editing the file by passing `key=value` arguments:

```
hive create exp -c hive.yaml \
  experiment_name=foo- \
  repo.branch=feature/try-hive \
  sandbox.resources.cpu=1
```

## Listing experiments

```
$ hive list exp
NAME                  AGENTS  STATUS          AGE
my-experiment-abc123  10/10   Running         5m
test-exp-xyz789       0/10    ImageBuilding   2h
debug-exp-abc789      5/10    InProgress      15m
```

| Column     | Meaning                                                    |
| ---------- | ---------------------------------------------------------- |
| **NAME**   | Experiment identifier                                      |
| **AGENTS** | `ready/total` — e.g. `8/10` means 8 of 10 agents are ready |
| **STATUS** | Current experiment phase (see below)                       |
| **AGE**    | Time since creation                                        |

Experiments progress through these phases:

| Status          | Description                            |
| --------------- | -------------------------------------- |
| `Pending`       | Experiment submitted, waiting to start |
| `ImageBuilding` | Building container images              |
| `InProgress`    | Agents are being initialized           |
| `Running`       | Agents are executing experiments       |
| `Completed`     | All agents finished successfully       |

## Viewing experiment details

```
$ hive get exp my-experiment-abc123
apiversion: v1alpha1
name: my-experiment-abc123
spec
  repo
    source:             https://github.com/your-org/repo.git
    branch:             main
    evaluation_script:  evaluation.py
    target_code:        main.py
  runtime
    agents:          10/10
    max_runtime:     -1
    max_iterations:  -1
  sandbox
    base_image:          python:3.14-slim
    evaluation_timeout:  60s
    setup_script:
      pip install -r requirements.txt
    resources:
      cpu:    2
      memory: 4Gi
status
  created: 2026-04-22T10:30:00Z (2h ago)
  phase:   Running
  message: Experiment is running successfully
```

Output sections:

* `name`: Experiment identifier
* `spec`: Experiment specification
  * `repo`: Source code repository configuration
  * `runtime`: Execution settings (agents shows ready/total, e.g., 10/10)
  * `sandbox`: Container environment and resources
* `status`: Current state
  * `created`: Creation timestamp and age
  * `phase`: Current lifecycle phase
  * `message`: Condition message (if available)

## Streaming logs

Stream logs for a running experiment with `hive logs`. The `--source` flag selects where the logs come from:

```
# Follow the coordinator logs live
hive logs my-experiment-abc123 --source coordinator
```

To inspect a specific sandbox worker, use `--source sandbox` together with `--worker` (0-based):

```
hive logs my-experiment-abc123 --source sandbox --worker 0
```

By default logs are followed live. Pass `--no-follow` to print the existing logs and exit:

```
hive logs my-experiment-abc123 --source coordinator --no-follow
```

## Stopping experiments

```
hive stop exp my-experiment-abc123
```

To stop multiple experiments at once:

```
hive stop exp exp-1 exp-2 exp-3
```

When stopping more than one experiment you'll be asked to confirm. Add `--yes` (or `-y`) to skip the confirmation prompt:

```
hive stop exp exp-1 exp-2 exp-3 -y
```

## Viewing the dashboard

The experiment dashboard, which contains detailed information about all Hive experiments launched by your team, can be accessed by using:

```
hive dashboard
```

Use `--no-browser` to print the URL without opening a browser.