> ## 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 Command Reference
> Full reference for the aven-stellar start and stop commands, including all options, examples, and the local files each command reads or writes.
The `aven-stellar` CLI — also invocable as `aven` after a global install — exposes two primary commands: `start` and `stop`. Together they bracket a work session, from the moment you begin coding to the moment you submit your verified report to the Aven dashboard.
***
## `aven start`
Starts recording project activity for the configured Aven stream. On first use in a repository, the command prompts for the dashboard URL and stream ID, then opens the browser for wallet authorization. On subsequent runs it reads the saved configuration and starts the session immediately.
### Usage
```bash theme={null}
npx aven-stellar start [options]
```
### Options
The Aven stream ID (digits only). Overrides any stream ID saved in `.aven/config.json`. Use this to switch between streams in the same repository.
The Aven dashboard URL. Defaults to `http://localhost:3000` when prompted interactively. Pass this flag to point the CLI at a hosted instance, for example `--dashboard https://aven.app`.
Skip the data-collection confirmation prompt that is shown before the session starts. Useful for CI pipelines and automated agents.
### Examples
```bash theme={null}
# Start a session using the saved configuration
npx aven-stellar start
# Override the stream ID
npx aven-stellar start --stream 42
# Point at a hosted dashboard and specify the stream
npx aven-stellar start --stream 42 --dashboard https://aven.app
# Skip the confirmation prompt (automation)
npx aven-stellar start --non-interactive
```
### What happens on `start`
1. Locates the repository root by walking up the directory tree to find `.git/`
2. Creates `.avenignore` with safe defaults if it does not already exist
3. Checks for an existing active session — exits with an error if one is found
4. Loads `.aven/config.json`, or runs first-time setup if the file is missing or a different stream ID was passed
5. Opens the browser for wallet authorization on first use, or if the saved token has expired
6. Verifies that the configured stream is active and that your wallet address is the recipient
7. Displays the data that will be collected and prompts for confirmation (bypassed by `--non-interactive`)
8. Writes session state to `.aven/session.json`
9. Spawns a detached background activity watcher process and records its PID
***
## `aven stop`
Stops the active session, generates the work report, and optionally submits it to the Aven dashboard for review and on-chain payment.
### Usage
```bash theme={null}
npx aven-stellar stop [options]
```
### Options
Your summary of the work done in this session. If omitted, the CLI prompts you interactively. This text appears as the worker statement in the submitted report.
Submit the previewed report without an additional confirmation prompt. Useful when you have already reviewed the report and want a single command to finalize the session.
Mark the project as fully completed and request the full remaining stream balance, rather than the amount calculated from active seconds at the stream rate.
### Examples
```bash theme={null}
# Stop interactively — will prompt for a message and submission confirmation
npx aven-stellar stop
# Provide a message, still prompts for submission confirmation
npx aven-stellar stop --message "Implemented input validation and wrote tests"
# Fully automated stop — no prompts
npx aven-stellar stop --message "Completed authentication module" --submit
# Final delivery — request full remaining balance and auto-submit
npx aven-stellar stop --message "Final delivery" --ended --submit
```
### What happens on `stop`
1. Sends `SIGTERM` to the background watcher process to stop activity tracking
2. Reads the final session state from `.aven/session.json`
3. Fetches current stream metadata from the dashboard (earned amount, rate per second)
4. Prompts for a worker statement if `--message` was not passed
5. Calculates Git change statistics: commits made, files changed, additions, deletions, and file categories
6. Builds the full `WorkSessionReport` and saves it to `.aven/report.json`
7. Prints the complete report to the terminal for review
8. Prompts for submission confirmation (bypassed by `--submit`)
9. Filters the report to include only verification-eligible files and submits it to the dashboard
10. Deletes `.aven/session.json` and prints the dashboard link for the submitted session
***
## `.avenignore`
The CLI automatically creates `.avenignore` at the repository root on first `start` if the file does not exist. It works exactly like `.gitignore` — add glob patterns to exclude paths from the session report. Both `.gitignore` and `.avenignore` are respected at the same time.
```bash theme={null}
# .avenignore — add your own exclusions below the defaults
*.env
*.pem
*.key
secrets/
private/
```
The default entries written by the CLI are:
```
.env
.env.*
*.pem
*.key
*.p12
node_modules/
.next/
dist/
build/
coverage/
.git/
```
***
## Local files
| File | Purpose |
| -------------------- | -------------------------------------------------------------- |
| `.aven/config.json` | Dashboard URL, stream ID, worker address, and auth token |
| `.aven/session.json` | Active session state — present only while a session is running |
| `.aven/report.json` | Latest generated report — overwritten on each `stop` |
| `.avenignore` | Glob patterns for paths excluded from the session report |
Add `.aven/` to your `.gitignore`. Session state and auth tokens should never be committed to version control.