> ## 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. # aven-stellar CLI: Complete Commands and Flags Reference > Complete reference for all aven-stellar commands: start, stop, status, and sessions. Covers every flag, error case, and the --ended settlement flow. This page is the complete reference for every `aven-stellar` command and flag. All commands can be run with `npx aven-stellar ` or, after a global install, with `aven `. See the [Installation](https://aven-docs.mintlify.site/cli/installation.md) page for setup instructions. *** ## `aven start` Start recording project activity for the configured Aven stream. ```bash theme={null} npx aven-stellar start ``` With flags: ```bash theme={null} npx aven-stellar start --stream --dashboard --non-interactive ``` ### Flags **--stream** `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. **--dashboard** `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. **--non-interactive** `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`): ``` Aven will collect: • relative file paths and change types • Git branch, commit, and diff statistics • session, active, and idle duration Aven will not collect file contents, keystrokes, screenshots, wallet secrets, or files excluded by .gitignore/.avenignore. ``` ### Error Cases | Condition | Result | | - | - | | A session is already active with a live watcher | Exits with an error — stop the existing session first | | A session exists but its watcher is no longer running | Exits with a description of the interrupted session — run `aven stop` to handle it or delete `.aven/session.json` to discard it | | The configured stream status is not `active` or `paused` | Exits with a descriptive error | | The authorized wallet is not the stream's recipient | Exits with an authorization error | | No commits exist in the repository | Exits — make an initial commit before running `aven start` | *** ## `aven stop` Stop the session, generate a work report, and optionally submit it to the Aven dashboard. ```bash theme={null} npx aven-stellar stop ``` With flags: ```bash theme={null} npx aven-stellar stop --message "Implemented the auth module" npx aven-stellar stop --message "Final delivery" --submit npx aven-stellar stop --ended npx aven-stellar stop --message "Completed all tasks" --submit --ended ``` ### Flags **--message** `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. **--submit** `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. **--ended** `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](#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 > [!TIP] > > 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 > [!WARNING] > > `--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. ```bash theme={null} npx aven-stellar status ``` No flags. The command reads `.aven/session.json` and `.aven/config.json` and prints a live summary: ``` SESSION ID Stream #42 Started 34m ago Branch main ACTIVITY Active 1823s Idle 240s Events 47 file changes WATCHER PID 12345 Status Running Last beat 12s ago RECORDED PAYMENT ESTIMATE Rate 0.0000100 USDC/s Est. amount 0.0182300 USDC ``` 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. ```bash theme={null} npx aven-stellar sessions ``` No flags. The command fetches the session list from the Aven dashboard and prints a summary sorted by most recent first: ``` Stream #42 status: active available: 5.2300000 USDC a1b2c3d4 SUBMITTED 0.0182300 USDC 2h ago e5f6g7h8 APPROVED 0.0091150 USDC 1d ago i9j0k1l2 DISPUTED 0.0364600 USDC 3d ago dispute: Commits do not match the described work ``` 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. ```bash theme={null} npx aven-stellar --version ``` To check the latest published version without using the cache: ```bash theme={null} npx --yes aven-stellar@latest --version ``` *** ## 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](https://aven-docs.mintlify.site/cli/automated-workers.md) page for the full guide. ```bash theme={null} # Start without prompts npx aven-stellar start \ --stream 42 \ --dashboard https://aven-chi.vercel.app \ --non-interactive # Work happens (automated tasks, AI agent, etc.) # Stop and submit automatically npx aven-stellar stop \ --message "Completed the assigned validation changes" \ --submit ``` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.