Skip to main content
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

​
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

​
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

​
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

​
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.
The default entries written by the CLI are:

​
Local files

Add .aven/ to your .gitignore. Session state and auth tokens should never be committed to version control.