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

# CLI

> Install the wwai command-line client to script datasets, training, inference, and jobs from your terminal or an agent.

The [`woodwide-cli`](https://pypi.org/project/woodwide-cli/) package installs **`wwai`** — a command-line client for the Wood Wide API. Output is JSON by default so scripts and agents can pipe results to `jq`.

<CardGroup cols={2}>
  <Card title="PyPI" icon="box" href="https://pypi.org/project/woodwide-cli/">
    Install, release history, and package README.
  </Card>

  <Card title="Console setup" icon="terminal" href="https://console.woodwide.ai/settings?tab=cli">
    Guided install steps in the developer console.
  </Card>
</CardGroup>

<Note>
  The CLI source repository is not public. Use [PyPI](https://pypi.org/project/woodwide-cli/) for the package README, the [console CLI tab](https://console.woodwide.ai/settings?tab=cli) for setup, and `wwai --help` for the full command reference.
</Note>

***

## Install

Requires **Python 3.12+**.

<Tabs>
  <Tab title="uv (recommended)">
    ```bash theme={null}
    uv tool install woodwide-cli
    wwai --help
    ```
  </Tab>

  <Tab title="pipx">
    ```bash theme={null}
    pipx install woodwide-cli
    wwai --help
    ```
  </Tab>

  <Tab title="pip">
    ```bash theme={null}
    pip install woodwide-cli
    wwai --help
    ```
  </Tab>
</Tabs>

***

## Authenticate

<Steps>
  <Step title="Create an API key">
    [Create a key](https://console.woodwide.ai/settings?tab=api-keys) in the console.
  </Step>

  <Step title="Save it locally">
    ```bash theme={null}
    wwai config set --api-key sk_your_api_key_here
    ```

    Stored in `~/.wwai/config.json`. You can also pass `--api-key` per command or set `WOODWIDE_API_KEY`.

    <Warning>
      Never commit API keys to source control.
    </Warning>
  </Step>

  <Step title="Confirm">
    ```bash theme={null}
    wwai --format table datasets list
    ```
  </Step>
</Steps>

***

## End-to-end example

Upload a dataset, train a prediction model, and run sync inference:

```bash theme={null}
UPLOAD=$(wwai datasets create --file train.csv --name "sales-q4")
DATASET=$(echo "$UPLOAD" | jq -r '.dataset.id')
INGEST_JOB=$(echo "$UPLOAD" | jq -r '.job_id')

wwai jobs wait "$INGEST_JOB"

TRAIN=$(wwai models train \
  --dataset "$DATASET" \
  --type prediction \
  --label-column revenue \
  --wait)
MODEL=$(echo "$TRAIN" | jq -r '.model.id')

wwai infer sync "$MODEL" --file new_data.csv --output-type json
```

For model types, training options, and task-specific guidance, see [Capabilities](/capabilities/overview). For HTTP details behind each command, see the [API reference](/api-reference/getting-started).

***

## CLI-specific behavior

<Tip>
  Use **`--wait`** on the command that enqueues a job (e.g. `models train ... --wait`) to block in the same shell. Use **`jobs wait JOB_ID`** to reattach later — useful for agents or a new terminal session.
</Tip>

**Output** — JSON by default. Add `--format table` for readable tables:

```bash theme={null}
wwai --format table datasets list
```

Progress from `--wait` and `jobs wait` goes to **stderr**; final JSON goes to **stdout**, so you can pipe to `jq` while watching status.

**Exit codes** for `--wait` and `jobs wait`:

| Code | Meaning                           |
| ---- | --------------------------------- |
| `0`  | Job succeeded                     |
| `1`  | Job failed, canceled, or rejected |
| `2`  | Timeout (job still running)       |

***

## Data connections

Import from connections configured in the [console](/connection):

```bash theme={null}
wwai connections list
wwai connections import CONNECTION_ID \
  --mode table --schema analytics --table orders --name "orders snapshot"
wwai jobs wait JOB_ID
```

***

## Command reference

Every subcommand exposes flags and examples via `--help`:

```bash theme={null}
wwai datasets --help
wwai models train --help
wwai infer batch --help
```

| Variable            | Description                                       |
| ------------------- | ------------------------------------------------- |
| `WOODWIDE_API_KEY`  | API key (`sk_...`)                                |
| `WOODWIDE_BASE_URL` | API base URL (default: `https://api.woodwide.ai`) |

***

## Next steps

<CardGroup cols={2}>
  <Card title="API quickstart" icon="code" href="/api-reference/getting-started">
    Same workflow with curl, JavaScript, or the Python SDK tab.
  </Card>

  <Card title="Python SDK" icon="python" href="/sdk-quickstart">
    Typed client for the same workflows from Python.
  </Card>
</CardGroup>