Skip to main content
This page is the complete reference for every aven-stellar command and flag. All commands can be run with npx aven-stellar <command> or, after a global install, with aven <command>. See the Installation page for setup instructions.

​
aven start

Start recording project activity for the configured Aven stream.
With flags:

​
Flags

​
string
The Aven stream ID (digits only). When provided, this value is compared against the saved configuration in .aven/config.json. If it differs from the saved stream ID, the CLI prompts you to reset and re-authorize. In --non-interactive mode, a mismatch exits with an error instead of prompting.
​
string
The full URL of the Aven dashboard (e.g. https://aven-chi.vercel.app). When provided and different from the saved URL, the CLI prompts you to reset and re-authorize. In --non-interactive mode, a mismatch exits with an error.
​
boolean
Skips the data collection confirmation prompt. Required for automated or CI environments. Fails immediately if the saved config is missing, needs re-authorization, or if --stream/--dashboard differ from the saved values.

​
Behavior

First run: The CLI prompts for the dashboard URL and stream ID, then opens your browser to /cli/authorize for Freighter wallet authorization. After authorization it saves the token to .aven/config.json and launches the background activity watcher. Subsequent runs: Reads .aven/config.json, re-validates the stream against the dashboard (confirming the stream is active and your wallet is still the recipient), refreshes the rate if it has changed, and immediately starts the background watcher. The activity watcher is a lightweight background process that monitors file change events. It records active vs. idle time without reading file contents and updates .aven/session.json with a periodic heartbeat. Before starting, the CLI prints a summary of what will be collected and asks for confirmation (skipped with --non-interactive):

​
Error Cases

​
aven stop

Stop the session, generate a work report, and optionally submit it to the Aven dashboard.
With flags:

​
Flags

​
string
A worker-written summary of what was accomplished during this session. Included in the submitted report and visible to the employer on the stream page. If omitted, the CLI prompts you to enter a summary interactively.
​
boolean
Submits the previewed report immediately without displaying an additional confirmation prompt. When this flag is omitted, the CLI prints the full report and asks before sending it to the dashboard.
​
boolean
Marks this as the final project session. Triggers delivery branch selection, verifies each selected branch’s head commit against the connected GitHub repository, and requests settlement of the remaining unreserved escrow. See The —ended flag in detail below.

​
Behavior

  1. Sends SIGTERM to the background watcher process and waits up to 3 seconds for it to exit
  2. Reads the final session state from .aven/session.json (the watcher writes its last heartbeat before exiting)
  3. Captures the current Git state — branch, commits since session start, diff statistics, and changed file paths
  4. Calculates the payment amount: active seconds × stream rate, capped by the unreserved escrow on the stream
  5. Writes the full report to .aven/report.json locally
  6. Displays the report for review
  7. If --submit is not passed: prompts before submitting to the dashboard
  8. On successful submission: deletes .aven/session.json and prints the submitted session ID and a link to review it
If submission fails after stopping, run npx aven-stellar stop again. The CLI retains the original stop time in .aven/session.json and retries the same report — the delay between the failure and the retry is not counted as work time.

​
The --ended Flag in Detail

Use --ended only for the project’s final work session. It activates a separate delivery flow on top of the normal stop:
  • The CLI lists all local branches and prompts you to select the delivery branches (or choose all)
  • For each selected branch, it resolves the head commit hash from your local Git history
  • It verifies each branch’s head commit against the connected GitHub repository via the Aven dashboard API
  • Branches that are missing from the remote or that don’t match the expected head commit are flagged with a warning — push them before requesting final payment
  • The delivery branch list, head commits, and verification results are included in the submitted report
On the dashboard side:
  • The server calculates the remaining unreserved escrow and converts it to a contract-compatible duration for the verify_work entrypoint
  • The real npm-tracked active seconds are preserved in the report separately from this compatibility duration
  • Pending or reserved payments must be resolved before a final session can be submitted
  • Final sessions require explicit employer approval in the dashboard — they are not automatically released
--ended triggers the final project settlement flow. Use it only when you are certain the project is complete and all prior sessions have been resolved. This action cannot be undone once the employer approves it.

​
aven status

Show the current session status and estimated payment amount.
No flags. The command reads .aven/session.json and .aven/config.json and prints a live summary:
The estimated payment is calculated from current active seconds multiplied by the saved stream rate. It is an estimate only — the final amount is capped by the available unreserved escrow at submission time. If the watcher heartbeat is stale (no update within the expected window), the status output notes that the watcher may have stopped.

​
aven sessions

List work sessions submitted to the configured stream.
No flags. The command fetches the session list from the Aven dashboard and prints a summary sorted by most recent first:
Session statuses include SUBMITTED, PENDING, APPROVED, DISPUTED, and RESPONSE_SUBMITTED. Disputed sessions show an excerpt of the dispute reason; sessions with a submitted worker response show the response excerpt.

​
aven --version

Print the installed package version.
To check the latest published version without using the cache:

​
Automated Usage Example

Once a repository is authorized (one-time human step), you can run complete sessions without any interactive prompts. See the Automated Workers page for the full guide.