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

# Install aven-stellar: Setup, Auth, and First Session

> Install the aven-stellar CLI via npx or npm global install. Requires Node.js 20+ and a Git repository. Authorize with your Freighter wallet on first use.

> [!NOTE]
>
> **Requirements before you start:**
>
> * **Node.js 20 or newer** — check with `node --version`
> * **npm** — bundled with Node.js
> * **A Git repository** — the CLI must be run from inside a repository with at least one commit
> * **Freighter wallet** — configured for Stellar testnet ([freighter.app](https://www.freighter.app/))
> * **An Aven stream** — where your wallet address is the designated recipient

## Option 1: Run with npx (Recommended)

No installation required. `npx` downloads and runs `aven-stellar` automatically, always resolving the latest published version:

```bash theme={null}
npx aven-stellar start
npx aven-stellar stop
```

For production use, pin to a specific version to guarantee reproducible behavior:

```bash theme={null}
npx aven-stellar@0.3.0 start
```

## Option 2: Global Install

Install `aven-stellar` once and use it across all your projects:

```bash theme={null}
npm install --global aven-stellar
```

After a global install, both the `aven` and `aven-stellar` command aliases are available on your `PATH`:

```bash theme={null}
aven start
aven stop
aven --version
```

## Force the Latest Version

When testing a newly published release, tell `npx` to bypass its cache and resolve the current package from the registry:

```bash theme={null}
npx --yes aven-stellar@latest --version
```

## First-Time Authorization

The first time you run `aven start` in a repository, the CLI guides you through a one-time setup to connect to your Aven stream and authorize your wallet.

**1. Open a terminal inside your Git repository**

Navigate to the project directory where your work will happen. The CLI requires at least one existing commit.

**2. Run aven start**

```bash theme={null}
npx aven-stellar start
```

**3. Enter the Aven dashboard URL**

When prompted, provide the Aven dashboard URL. For the hosted instance:

```
https://aven-chi.vercel.app
```

For local development, use `http://localhost:3000`.

**4. Enter your stream ID**

Enter the stream ID provided by your employer (digits only). This identifies the payment agreement you are working against.

**5. Authorize in the browser**

The CLI opens `/cli/authorize` in your default browser. The Aven dashboard will prompt you to sign an authorization message with your Freighter wallet.

> [!NOTE]
>
> The CLI never receives your wallet secret key. It only receives a scoped, short-lived authorization token after you sign the request in your browser.

**6. Authorization complete**

After signing, the browser confirms success and the CLI continues. The authorization token is saved to `.aven/config.json` for all future sessions in this repository.

## The `.aven/` Directory

After first-time setup, the CLI creates a `.aven/` directory in your repository root. This directory holds local session state and should **not** be committed.

| File | Contents |
| - | - |
| `.aven/config.json` | Dashboard URL, stream ID, contract ID, and auth token |
| `.aven/session.json` | Active session state (start time, active seconds, watcher PID) |
| `.aven/report.json` | Last generated work report, written locally before submission |

The `.aven/` directory itself is created with mode `0700` (owner access only), and each file inside is created with mode `0600` (owner read/write only).

> [!WARNING]
>
> Add `.aven/` to your `.gitignore`. The CLI automatically creates `.avenignore` to protect sensitive paths, but `.aven/config.json` contains your authorization token and must not be committed to version control.

The CLI also creates `.avenignore` in your repository root on first `aven start`. This file works like `.gitignore` and controls which paths are excluded from work reports. See the [Privacy & Safety](https://aven-docs.mintlify.site/cli/privacy-and-safety.md) page for details.

## Re-Authorization

If your dashboard URL or stream ID changes, you need to re-authorize:

**Option A — Delete and re-run:**

```bash theme={null}
rm .aven/config.json
npx aven-stellar start
```

**Option B — Pass flags to trigger a reset prompt:**

```bash theme={null}
# Passing a different --dashboard or --stream than what's saved
# prompts you to reset and re-authorize
npx aven-stellar start --stream <new-stream-id> --dashboard <new-url>
```

If you pass `--non-interactive` alongside a changed `--dashboard` or `--stream` flag, the CLI exits with an error instead of prompting. Delete `.aven/config.json` manually before running the automated workflow.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.