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

# Get Paid for Verified Work Using the aven-stellar CLI

> Install the aven-stellar CLI, connect your Freighter wallet to an Aven stream, and start tracking verified work sessions to earn exact payments.

This guide walks you through everything you need to start earning on Aven as a freelancer. By the end, you will have the `aven-stellar` CLI installed, your Freighter wallet authorized to a payment stream, and a clear understanding of how to start sessions, track your active work, and submit verified reports so your employer can release payment directly from the smart contract.

> [!NOTE]
>
> **Prerequisites**
>
> Before you begin, make sure you have the following:
>
> * **Node.js 20 or newer** installed on your machine
> * **A Git repository** for the project you are being paid to work on (at least one commit must exist)
> * **Freighter browser extension** installed and configured for the Stellar testnet
> * **The stream ID and Aven dashboard URL** provided by your employer
> * Your wallet address must be the **designated recipient address** on the stream — the CLI verifies this during authorization and will reject a mismatch

**1. Install the CLI**

You can run `aven-stellar` without installing it globally using `npx`, or install it once and use the shorter `aven` alias.

```bash npx (no install required) theme={null}
# Run any command directly — npx downloads the package on first use
npx aven-stellar start
npx aven-stellar stop
npx aven-stellar status
```

```bash Global install theme={null}
# Install once, then use the short alias from any terminal
npm install --global aven-stellar

aven start
aven stop
aven status
```

> [!NOTE]
>
> Both `aven` and `aven-stellar` are registered as command aliases by the global install. All examples in this guide use `npx aven-stellar` so they work without a global installation.

**2. Authorize your wallet**

Before the CLI can submit sessions on your behalf, it needs a wallet-signed token that proves you are the stream's designated recipient.

1. Open a terminal **inside your project's Git repository**.
2. Run the start command:
   ```bash theme={null}
   npx aven-stellar start
   ```
3. When prompted, enter the **Aven dashboard URL** your employer shared (for example, `https://aven-chi.vercel.app`).
4. Enter the **stream ID** — a numeric identifier your employer can find on the stream page.
5. The CLI opens the `/cli/authorize` page in your browser.
6. **Sign the authorization message** in Freighter. This is a short-lived device request — it is not a transaction and does not move any funds.

Once signed, the CLI receives a scoped token and stores it in `.aven/config.json`. This token lets the CLI read your streams, submit session reports, and request review. It cannot create new streams or approve your own payment requests.

> [!NOTE]
>
> The CLI **never receives, stores, or transmits your Stellar secret key**. Authorization is entirely wallet-signed through Freighter in your browser.

**3. Start a work session**

With your wallet authorized, starting a session is a single command:

```bash theme={null}
npx aven-stellar start
```

The CLI will display exactly what it plans to collect and ask you to confirm before proceeding:

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

Start this work session? [Y]:
```

After you confirm, a lightweight background activity watcher launches and begins counting verified active seconds.

**Passing flags to skip prompts:**

```bash theme={null}
# Provide the stream ID and dashboard URL directly (useful for the first run in a new repo)
npx aven-stellar start --stream <stream-id> --dashboard <url>

# Skip the collection confirmation — useful for automated or scripted workflows
npx aven-stellar start --non-interactive
```

**4. Work normally**

Once the session is running, just work in your repository as you always would — write code, run tests, open files, and commit your changes. You do not need to keep a special terminal window open or interact with the CLI again until you are ready to stop.

The background activity watcher monitors file-system events and Git activity within your repository, recording:

* **Active seconds** — time during which genuine file-system or Git activity was detected
* **Idle seconds** — time where no activity was observed
* **Git statistics** — branch, commit references, changed paths, and diff counts

All session state is written locally to the **`.aven/`** directory in your repository root.

> [!NOTE]
>
> **Do not commit the `.aven/` directory.** It contains local session state that is specific to your machine. The CLI automatically creates a `.avenignore` file with safe defaults and also respects your existing `.gitignore`.

**5. Check session status (optional)**

At any point during an active session, you can check what the CLI has recorded so far:

```bash theme={null}
npx aven-stellar status
```

This prints a live summary of the current session, including:

| Field | Description |
| - | - |
| Session ID | Unique identifier for this work session |
| Stream | The connected stream number |
| Started | How long ago the session began |
| Active | Total active seconds recorded so far |
| Idle | Total idle seconds recorded so far |
| Events | Number of file-change events detected |
| Watcher status | Whether the background watcher is running |
| Estimated payment | Active seconds × stream rate (live estimate) |

The estimated payment shown by `status` is a local calculation based on the saved stream rate. The final on-chain amount is determined by the Aven verifier at submission time.

**6. Stop and submit**

When your work period is finished, stop the session and generate a report:

```bash theme={null}
npx aven-stellar stop
```

The CLI will:

1. Signal the background watcher to stop and wait for it to exit cleanly
2. Calculate final Git change statistics and active time
3. Ask for a **delivery summary** — a short statement describing what you worked on
4. Print the full session report for your review
5. Ask whether you want to submit the report to the dashboard

**Optional flags:**

```bash theme={null}
# Include a pre-written delivery summary, skipping the prompt
npx aven-stellar stop --message "Implemented the authentication module"

# Submit immediately after the report preview, without a second confirmation prompt
npx aven-stellar stop --submit

# Mark this as the final project session and request release of remaining escrow
npx aven-stellar stop --message "Final delivery" --submit --ended
```

After a successful submission, the CLI deletes the local session file and prints a link to the stream page where your employer can review the report.

> [!TIP]
>
> **If submission fails after stopping**, run `npx aven-stellar stop` again. The CLI retains the original stop timestamp and retries the same report — the delay is never counted as additional work time.

**7. Wait for employer review**

After submission, the work report appears under **WORK SESSIONS** on the stream page in the Aven dashboard. Your employer will:

1. Open the stream page and review your work report, including Git statistics, active time, changed files, and your delivery statement
2. **Approve** the session — the smart contract automatically reserves and releases the calculated payment to your wallet address
3. Or **dispute** the session — which pauses release and opens a conversation for resolution

You do not need to take any further action unless a dispute is raised. Once the employer approves, the contract releases the payment without requiring any additional steps from you.

## Payment calculation

Aven calculates your payment automatically from verified data — you never enter your own payment amount.

| Session type | How payment is calculated |
| - | - |
| **Normal session** | `active seconds × stream rate` |
| **Final session (`--ended`)** | Remaining unreserved escrow in the stream |

Both amounts are:

* **Capped** by the stream's unreserved escrow balance at submission time
* **Enforced on-chain** — the Soroban smart contract independently verifies the calculation before releasing funds
* **Denominated** in the asset the stream was created with (XLM or USDC on Stellar testnet)

The Aven verifier on the server reserves the payment amount when you submit your report. Your employer's approval in the dashboard triggers the final on-chain release.

## Final delivery sessions

Use the `--ended` flag when submitting the **last session of a project** to signal that work is complete and request release of the stream's remaining unreserved escrow.

```bash theme={null}
npx aven-stellar stop --ended
```

When you pass `--ended`, the CLI:

1. **Prompts you to select delivery branches** — choose from your local branches or select all
2. **Resolves the head commit** of each selected branch
3. **Verifies branch commits** against the connected GitHub repository — branches that are not pushed will be flagged with a warning
4. **Attaches the delivery record** to the report before submission

**Important constraints for final sessions:**

* **Pending or reserved session payments must be resolved first.** The server will reject a final session submission if any earlier sessions are still awaiting approval or dispute resolution.
* The `--ended` flag still **requires explicit employer approval** in the Aven dashboard. The escrow is not released automatically — your employer reviews the delivery record and approves the final release.
* If any selected branches are not yet pushed to the remote, the CLI will warn you. Push them before submitting to ensure the delivery record is fully verified.

> [!TIP]
>
> If a stopped session failed to submit, run `npx aven-stellar stop` again. The CLI keeps the original stop time and retries without counting the delay as work.

## Next steps

> **[CLI Command Reference](https://aven-docs.mintlify.site/cli/commands.md)**
>
> Complete reference for all `aven-stellar` commands and flags, including `start`, `stop`, `status`, and `sessions`.

> **[Privacy and Safety](https://aven-docs.mintlify.site/cli/privacy-and-safety.md)**
>
> Learn exactly what the CLI collects, what it never touches, and how your wallet authorization is scoped and protected.

> **[Freelancer Workflow](https://aven-docs.mintlify.site/workflows/freelancer-workflow.md)**
>
> End-to-end walkthrough of a typical engagement — from receiving a stream invitation to final payment release.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.