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

npx aven-stellar start [options]

Options

--stream · string

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.

--dashboard · string

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.

--non-interactive · boolean

Skip the data-collection confirmation prompt that is shown before the session starts. Useful for CI pipelines and automated agents.

Examples

# 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

npx aven-stellar stop [options]

Options

--message · string

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 · boolean

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.

--ended · boolean

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

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

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