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

# aven-stellar CLI: Track Work and Submit Sessions

> The aven-stellar npm package lets workers track active work time, capture Git statistics, and submit verifiable session reports to Aven.

`aven-stellar` is the npm package workers run inside a Git repository to track active work time, capture Git statistics, and submit verifiable session reports to Aven. It records what changed during a work period — branch names, commit metadata, and diff statistics — and packages that data into a structured report that stream senders can review and approve on-chain.

## Requirements

Before using `aven-stellar`, make sure you have the following in place:

* **Node.js v20 or newer** — the CLI uses native async APIs available from Node.js 20
* **A Git repository** — all session tracking is anchored to Git history and file changes
* **An existing Aven payment stream** where you are the recipient — create one on the Aven dashboard before starting your first session
* **Freighter wallet browser extension** — required for the one-time authorization step that connects the CLI to your Stellar address

## Installation

You can run `aven-stellar` without a global install, or install it once and use the shorter `aven` alias everywhere.

<CodeGroup>
  ```bash npx (no install) theme={null}
  npx aven-stellar start
  npx aven-stellar stop
  ```

  ```bash Global install theme={null}
  npm install --global aven-stellar
  aven start
  aven stop
  ```
</CodeGroup>

## Typical Workflow

<Steps>
  <Step title="Open a terminal inside your Git repository">
    Navigate to the root of the project you are being paid to work on. The CLI must be run from within a Git repository.
  </Step>

  <Step title="Run `npx aven-stellar start`">
    On first use, the CLI prompts for your Aven dashboard URL and stream ID, then opens the dashboard in your browser so you can authorize your Freighter wallet. On subsequent runs in the same repository, it reads the saved configuration and starts immediately.
  </Step>

  <Step title="Work normally and make commits">
    The CLI spawns a lightweight background watcher that monitors file system activity. Continue coding and committing as you normally would — the watcher tracks active versus idle time automatically.
  </Step>

  <Step title="Run `npx aven-stellar stop`">
    When your work period ends, run `stop` to terminate the background watcher, calculate Git change statistics, and display the full session report. Review it, then confirm to submit it to the Aven dashboard.
  </Step>
</Steps>

## Local State

The CLI stores all session state in a `.aven/` directory at the root of your repository. **Do not commit this directory.** Add it to your `.gitignore`:

```bash theme={null}
echo ".aven/" >> .gitignore
```

The three files the CLI reads and writes are:

| File                 | Purpose                                                                                               |
| -------------------- | ----------------------------------------------------------------------------------------------------- |
| `.aven/config.json`  | Dashboard URL, stream ID, worker address, and auth token — written after the first successful `start` |
| `.aven/session.json` | Active session state — present only while a session is running; deleted after `stop`                  |
| `.aven/report.json`  | Latest generated report — written by `stop` and overwritten on each run                               |

## Configuration File

After the first successful `start`, the CLI writes `.aven/config.json` with your dashboard URL, stream ID, and worker address. On every subsequent run in that repository, the CLI reads this file automatically — you do not need to re-enter your settings.

To work on a different stream in the same repository, pass `--stream <id>` to override the saved stream ID:

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

The CLI will re-authorize if the new stream ID does not match the saved configuration.

<Note>
  The CLI never asks for or stores your Stellar secret key. Authorization uses a time-limited token obtained via the Aven dashboard when you approve the connection with your Freighter wallet.
</Note>