# Install Raw

> Install Raw from npm, GitHub or a source checkout, then create the starter configuration.

## Requirements

- **Node.js 22.13 or later.**
- **Bash.** Raw’s `bash` tool runs commands through Bash.

Raw is published on npm as [`@tlelabs/raw`](https://www.npmjs.com/package/@tlelabs/raw). The installed command is `raw`.

## Choose an install method

**npm (recommended)**

Install the latest release globally:

```sh
npm install -g @tlelabs/raw
```

**Try without installing**

Run the CLI once through `npx`:

```sh
npx @tlelabs/raw --help
```

**Latest from GitHub**

Install the current default branch. This runs the package’s `prepare` build, so it downloads build tooling and takes longer than an npm install.

```sh
npm install -g github:lploc94/raw-cli
```

**From a checkout**

Build from source when you want to work on Raw itself. `npm ci` also builds the project.

```sh
git clone https://github.com/lploc94/raw-cli.git
cd raw-cli
npm ci
npm install -g .
```

## Create the starter configuration

Run the configuration initializer once:

```sh
raw config init
```

This creates `~/.config/raw/config.json`, or `$XDG_CONFIG_HOME/raw/config.json` when `XDG_CONFIG_HOME` is set. The file is created with owner-only permissions (mode `0600`). The initializer does not overwrite an existing file.

The starter file defines:

- a default agent named `raw`, and
- a model alias `local` that points to an Ollama-compatible endpoint at `http://127.0.0.1:11434/v1`, with the placeholder model ID `YOUR_INSTALLED_MODEL`.

Before your first task, replace the placeholder model ID with a model you have installed. The [Quickstart](https://raw.tlelabs.com/docs/start/quickstart/) shows how.

## Check the installation

```sh
raw --help
raw config list
```

`raw config list` reports each agent’s model, endpoint and tool selection. It does not print credentials.

## Where Raw stores files

| Data           | Location                                                                                       |
| -------------- | ---------------------------------------------------------------------------------------------- |
| Configuration  | `~/.config/raw/config.json` (or `$XDG_CONFIG_HOME/raw/`)                                       |
| Saved sessions | `~/.local/state/raw/sessions.sqlite` (or `$XDG_STATE_HOME/raw/`), with payload files beside it |

> **Note:**
>
> Session history is kept for seven days after the last committed conversation activity, by default. See [Sessions](https://raw.tlelabs.com/docs/guides/sessions/) for retention settings and backup guidance.

## Update or uninstall

To update to the latest release, run:

```sh
npm install -g @tlelabs/raw@latest
```

Check the installed version with `raw --version`. Release notes are on [GitHub releases](https://github.com/lploc94/raw-cli/releases).

To uninstall the command, run:

```sh
npm uninstall -g @tlelabs/raw
```

This removes the installed package. It does not remove your configuration or saved sessions. Delete `~/.config/raw/` and `~/.local/state/raw/` yourself if you no longer need them. Back up the state directory first if you want to keep any session history.

> **Installed before the npm release?**
>
> Builds packed before 0.1.0 reached npm were installed under the package name `raw-cli`. Run `npm uninstall -g raw-cli` first; otherwise npm refuses to install `@tlelabs/raw` because both provide the `raw` command.