> ## 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.

# aven-stellar CLI: Privacy-Conscious Work Session Tracking

> aven-stellar is the official Aven CLI for tracking Git work sessions, calculating verified payment amounts, and submitting reports to Aven payment streams.

`aven-stellar` is the official Node.js CLI for Aven — a Stellar-based protocol for funding work, measuring active delivery, and releasing exact payments. It records active coding time and Git change metadata for an existing Aven payment stream, then generates a structured, reviewable report that can be submitted to the Aven dashboard for employer approval.

The CLI is designed around a single principle: workers deserve a verifiable record of what changed during a work period without giving up privacy. File contents, keystrokes, and wallet secrets never leave the machine.

## Key Facts

| Property | Value |
| - | - |
| npm package name | `aven-stellar` |
| Current version | `0.3.0` |
| Command aliases | `aven` and `aven-stellar` (both installed) |
| Node.js requirement | 20 or newer |
| Runtime environment | Any Git repository |

## What aven-stellar Does

* **Starts and stops work sessions** — records session start time, active vs. idle time, and Git state
* **Tracks active time** — a lightweight background watcher detects file change events to distinguish active coding from idle time
* **Generates reports** — captures branch, commits since session start, relative changed file paths, and diff statistics
* **Calculates payment amounts** — multiplies verified active seconds by the stream's on-chain rate, capped by unreserved escrow
* **Submits to the Aven dashboard** — sends the structured report to the stream page for employer review and approval

## What aven-stellar Does NOT Do

* Does **not** upload source files or file contents
* Does **not** record keystrokes, mouse movements, or screenshots
* Does **not** request or store your Stellar secret key
* Does **not** execute project code, tests, or scripts
* Does **not** install project dependencies
* Does **not** read files excluded by `.gitignore` or `.avenignore`

## Commands Overview

| Command | Description |
| - | - |
| `aven start` | Start recording a work session |
| `aven stop` | Stop, generate a report, and optionally submit it |
| `aven status` | Show current session status and estimated payment |
| `aven sessions` | List submitted sessions for the configured stream |

## Quick Example

```bash theme={null}
npx aven-stellar start
# ... work normally and commit changes ...
npx aven-stellar stop --message "Implemented auth module"
```

On first run, `start` asks for your dashboard URL and stream ID, then opens your browser to authorize with your Freighter wallet. On subsequent runs, it reads the saved configuration from `.aven/config.json` and launches a background activity watcher immediately.

When you run `stop`, the CLI calculates the payment amount from your recorded active time, displays the full report for review, and asks before submitting to the dashboard.

## Explore the CLI

> **[Installation](https://aven-docs.mintlify.site/cli/installation.md)**
>
> Install aven-stellar via npx or npm global install. Set up your first authorization.

> **[Commands](https://aven-docs.mintlify.site/cli/commands.md)**
>
> Complete reference for all commands and flags: start, stop, status, and sessions.

> **[Privacy & Safety](https://aven-docs.mintlify.site/cli/privacy-and-safety.md)**
>
> Exactly what data the CLI records, what it never accesses, and how local state is managed.

> **[Automated Workers](https://aven-docs.mintlify.site/cli/automated-workers.md)**
>
> Run aven-stellar non-interactively for AI agents and automated pipelines.


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