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

# Flags

> All canonical flags for the harmstack CLI, organized by command.

Use this page as the customer-facing reference for `harmstack` flags.

<Tip>
  This page intentionally shows canonical kebab-case flags only (for example `--job-id`, `--benchmark-id`, `--unit-count`).
</Tip>

## Global and shared flags

These flags apply to the `harmstack` root command and `harmstack init`.

### Authentication and endpoint targeting

<ParamField path="--harmstack-api-key" type="string">
  Your Harmstack API key for account and job APIs.

  **Env fallback:** `HARMSTACK_API_KEY`

  **Example:**

  ```bash theme={null}
  harmstack init --harmstack-api-key "$HARMSTACK_API_KEY"
  ```
</ParamField>

<ParamField path="--target-model-endpoint" type="string">
  URL of the model API endpoint to benchmark.

  **Example:**

  ```bash theme={null}
  --target-model-endpoint https://api.openai.com/v1/responses
  ```
</ParamField>

<ParamField path="--target-model-api-key" type="string">
  Bearer token for your target model endpoint. Required when using `--consentandskip`.

  **Env fallback:** `TARGET_MODEL_API_KEY`

  **Example:**

  ```bash theme={null}
  --target-model-api-key "$TARGET_MODEL_API_KEY"
  ```
</ParamField>

<ParamField path="--provider" type="string" default="openai">
  API shape for your target endpoint.

  Accepted values:

  * `openai`
  * `openai_responses`
  * `gemini`
  * `raw`

  **Example:**

  ```bash theme={null}
  --provider openai_responses
  ```
</ParamField>

<ParamField path="--model" type="string">
  Model name used in requests. Ignored when `--provider=raw`.

  **Example:**

  ```bash theme={null}
  --model gpt-4o-mini
  ```
</ParamField>

### Benchmark selection and run behavior

<ParamField path="--benchmark-id" type="integer[]">
  Benchmark IDs to run. Repeat the flag or pass a comma-separated list.

  **Examples:**

  ```bash theme={null}
  --benchmark-id 2 --benchmark-id 3
  --benchmark-id=2,3
  ```
</ParamField>

<ParamField path="--unit-count" type="integer[]">
  Number of human-annotated unit tests per benchmark job (1 to 10). Must align with `--benchmark-id` order and length.

  **Example:**

  ```bash theme={null}
  --benchmark-id 2 --unit-count 5 --benchmark-id 3 --unit-count 3
  ```
</ParamField>

<ParamField path="--consentandskip" type="boolean" default="false">
  Skip interactive prompts and run non-interactively. Recommended for CI and scripting.

  **Example:**

  ```bash theme={null}
  harmstack --haystack --consentandskip --provider openai_responses --benchmark-id 2 --unit-count 1
  ```
</ParamField>

<ParamField path="--header" type="string[]">
  Optional HTTP headers added to every request to your model endpoint. Repeat as needed.

  **Example:**

  ```bash theme={null}
  --header "X-Custom-Header: value" --header "X-Trace-Id: run-123"
  ```
</ParamField>

<ParamField path="--haystack" type="boolean" default="false">
  Run the Haystack benchmarking flow directly from the root `harmstack` command.

  **Example:**

  ```bash theme={null}
  harmstack --haystack --consentandskip --provider openai --benchmark-id 2 --unit-count 1
  ```
</ParamField>

***

## harmstack compare-jobs flags

<ParamField path="--job-a" type="string">
  UUID of the first job.

  **Example:**

  ```bash theme={null}
  harmstack compare-jobs --job-a=550e8400-e29b-41d4-a716-446655440000 --job-b=6ba7b810-9dad-11d1-80b4-00c04fd430c8
  ```
</ParamField>

<ParamField path="--job-b" type="string">
  UUID of the second job.

  **Example:**

  ```bash theme={null}
  harmstack compare-jobs --job-a=550e8400-e29b-41d4-a716-446655440000 --job-b=6ba7b810-9dad-11d1-80b4-00c04fd430c8
  ```
</ParamField>

***

## harmstack list-jobs flags

<ParamField path="--format" type="string" default="table">
  Output format.

  Accepted values: `table`, `csv`

  **Example:**

  ```bash theme={null}
  harmstack list-jobs --format csv --limit 20 --status completed
  ```
</ParamField>

<ParamField path="--limit" type="integer" default="10">
  Maximum jobs to return.

  **Example:**

  ```bash theme={null}
  harmstack list-jobs --limit 25
  ```
</ParamField>

<ParamField path="--status" type="string" default="completed">
  Status filter.

  Accepted values: `completed`, `failed`, `all`

  **Example:**

  ```bash theme={null}
  harmstack list-jobs --status all
  ```
</ParamField>

***

## harmstack show-job flags

<ParamField path="--job-id" type="string">
  UUID of the job to inspect.

  **Examples:**

  ```bash theme={null}
  harmstack show-job --job-id=550e8400-e29b-41d4-a716-446655440000
  harmstack show-job 550e8400-e29b-41d4-a716-446655440000
  ```
</ParamField>

***

## harmstack stats flags

<ParamField path="--limit" type="integer" default="30">
  Number of recent completed jobs to include in aggregate calculations.

  **Example:**

  ```bash theme={null}
  harmstack stats --limit 50
  ```
</ParamField>

<ParamField path="--since" type="string">
  Date filter in `YYYY-MM-DD` format.

  **Example:**

  ```bash theme={null}
  harmstack stats --since 2025-01-01
  ```
</ParamField>