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

# Privacy and Safety Guarantees of the aven-stellar CLI

> aven-stellar is designed to protect your privacy. Learn exactly what data the CLI records, what it never accesses, and how local state is managed.

Privacy is a core design principle of `aven-stellar`, not an afterthought. The CLI is built around a strict boundary: it records enough information to verify that meaningful work happened, and nothing more. Every collection decision was made with the assumption that workers should never have to choose between getting paid and keeping their code private.

***

## What the CLI Records

The following data is included in a submitted work report:

| Category | What is collected |
| - | - |
| **Session timing** | Start time, stop time, and total active seconds (excluding idle time) |
| **Git branch** | The branch name active at session start |
| **Commit metadata** | Commit hashes and commit messages (not file contents) |
| **Changed file paths** | Relative paths only — not absolute paths, not file contents |
| **Diff statistics** | Lines added and lines deleted per file (not the actual diff) |
| **Git status summary** | Modified, added, deleted, and untracked file counts |
| **Worker delivery statement** | Free-text summary written by the worker, only if `--message` is provided |

The payment amount is derived automatically from tracked active seconds multiplied by the stream's on-chain rate. Workers do not enter or negotiate the payment amount themselves.

***

## What the CLI Never Does

> [!WARNING]
>
> **The following actions are explicitly outside the CLI's design:**
>
> * **Never requests or stores your Stellar secret key.** Authorization uses a scoped browser-signed token, not your wallet credentials.
> * **Never executes project code, tests, or scripts.** The CLI only reads Git metadata; it does not `npm install`, `npm test`, or run any project command.
> * **Never installs project dependencies.** The CLI's own runtime dependencies are self-contained.
> * **Never records keystrokes, mouse movements, or screenshots.** Activity tracking is based solely on filesystem change events.
> * **Never uploads complete source files.** Only relative file paths and line-count statistics appear in the report.
> * **Never reads files excluded by `.gitignore` or `.avenignore`.** Both ignore files are respected before any path is included in a report.

***

## The `.avenignore` File

When you run `aven start` for the first time in a repository, the CLI automatically creates `.avenignore` in your repository root. This file works exactly like `.gitignore`: any path matching a pattern in `.avenignore` is excluded from the work report.

The default `.avenignore` created by the CLI protects the most common sensitive paths:

```
.env
.env.*
*.pem
*.key
*.p12
node_modules/
.next/
dist/
build/
coverage/
.git/
```

You can add any additional paths that should never appear in a work report. The CLI also applies a built-in secret pattern filter — paths that match patterns like `secret`, `credential`, `private_key`, or `password` are automatically excluded regardless of `.avenignore`.

The CLI respects **both** `.gitignore` and `.avenignore` simultaneously. Any path excluded by either file is omitted from the report.

***

## Local State Storage

All CLI state is stored in the `.aven/` directory at your repository root. This directory is created with mode `0700` (owner access only), and each file inside it is created with mode `0600` (owner read/write only).

| File | Purpose |
| - | - |
| `.aven/config.json` | Dashboard URL, stream ID, contract ID, and authorization token |
| `.aven/session.json` | Active session state: start time, active seconds, idle seconds, watcher PID, and heartbeat timestamp |
| `.aven/report.json` | The last generated work report, written locally before any submission attempt |

> [!WARNING]
>
> **Do not commit `.aven/` to version control.** Add it to your `.gitignore`:
>
> ```
> .aven/
> ```
>
> The `.aven/config.json` file contains your authorization token. If it is committed and pushed to a public repository, it could allow others to submit sessions under your identity until the token expires.

The `.avenignore` file created automatically by the CLI includes `.aven/` in its patterns, which prevents the directory's contents from appearing in change reports. However, this does **not** prevent the directory from being committed — add it to `.gitignore` as well.

If submission fails, the report is retained in `.aven/report.json` and `.aven/session.json` preserves the original stop time. Running `aven stop` again retries the submission without adding the delay as work time.

***

## Authorization Token Scope

The Aven CLI uses a device authorization flow. When you run `aven start` for the first time, the CLI opens `/cli/authorize` in your browser and asks you to sign a short-lived request with your Freighter wallet. The resulting token is scoped and cannot perform all dashboard actions.

**The CLI token CAN:**

* Read the authorized worker's streams and stream metadata
* Submit work session reports to streams where the wallet is the recipient
* Request employer review of a submitted session

**The CLI token CANNOT:**

* Create new streams or modify stream parameters
* Approve the worker's own sessions
* Access another user's streams or session data
* Sign on-chain transactions directly

This scope means that even if `.aven/config.json` is accidentally exposed, an attacker can only submit work reports to your own streams — they cannot approve payments or access other users' data.


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