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

# Complete Freelancer Workflow: Track Work and Get Paid

> A complete guide to the freelancer experience in Aven: authorizing the CLI, running work sessions, submitting reports, and receiving verified payments.

As a freelancer (stream recipient) on Aven, you use the `aven-stellar` CLI to record privacy-conscious Git work sessions and submit verifiable reports to your payment stream. This page walks through every step — from installing the CLI to receiving payment in your Freighter wallet.

```mermaid theme={null}
flowchart TD
  A[Receive stream ID from employer] --> B[Install aven-stellar CLI]
  B --> C[Open terminal in project repo]
  C --> D[Run: aven-stellar start]
  D --> E{First time?}
  E -->|Yes| F[Enter dashboard URL + stream ID]
  F --> G[Sign auth in browser with Freighter]
  G --> H[CLI authorized]
  E -->|No| H
  H --> I[Activity watcher starts]
  I --> J[Work normally — commit changes]
  J --> K[Run: aven-stellar stop]
  K --> L[Review work report preview]
  L --> M{Submit?}
  M -->|Yes| N[Report submitted to stream]
  M -->|No| O[Discard - no payment]
  N --> P[Request review from employer]
  P --> Q[Wait for approval]
  Q --> R[Payment released to wallet]
  R --> S[Attestation minted]
```

## Step-by-step guide

**1. Install the aven-stellar CLI**

You can run the CLI without a global installation using `npx`, or install it globally for shorter commands.

**Using npx (recommended for most freelancers):**

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

**Global installation:**

```bash theme={null}
npm install --global aven-stellar

# Then use the short alias:
aven start
aven stop
```

The CLI requires **Node.js 20 or newer** and must be run from inside a Git repository.

> [!TIP]
>
> If you need to force `npx` to resolve the latest published version after an update, run:
>
> ```bash theme={null}
> npx --yes aven-stellar@latest --version
> ```

**2. First-time authorization**

The first time you run `aven-stellar start` in a repository, the CLI needs to link itself to your Aven stream and your Freighter wallet.

You will be prompted for:

1. **Dashboard URL** — the base URL of the Aven web application (e.g. `https://aven-chi.vercel.app`). Use `http://localhost:3000` if you are testing against a local server.
2. **Stream ID** — the stream ID provided by your employer.

After you enter these values, the CLI opens `/cli/authorize` in your browser. Sign the authorization request with Freighter. This produces a scoped, short-lived device token that is stored locally under `.aven/`.

> [!NOTE]
>
> The authorization token can read your streams, submit sessions, and request review. It **cannot** create streams or approve your own work — those actions are reserved for the stream sender.

Once authorized, subsequent `start` commands in the same repository skip the authorization flow entirely.

**3. Start a work session**

Open a terminal inside the Git repository where you will be working, then run:

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

The CLI launches a lightweight background activity watcher that tracks active time and detects idle periods.

**Optional flags:**

| Flag | Description |
| - | - |
| `--stream <stream-id>` | Provide the stream ID directly instead of being prompted. |
| `--dashboard <url>` | Provide the dashboard URL directly instead of being prompted. |
| `--non-interactive` | Skip the data-collection confirmation prompt. Useful for automated workers. |

```bash theme={null}
# Example with flags:
npx aven-stellar start --stream abc123 --dashboard https://aven-chi.vercel.app
```

> [!NOTE]
>
> You can only have one active session per repository at a time. If a session is already running, you must stop it before starting a new one.

**4. Work normally and commit your changes**

With the session running, work as you normally would in your editor. The CLI watcher runs silently in the background and records:

* Active vs. idle time (keyboard and mouse activity signals)
* Git branch and commit metadata
* Changed file paths (relative only — never file contents)
* Additions and deletions

Commit your work at natural checkpoints — the CLI captures the full commit range from session start to session stop.

> [!NOTE]
>
> The CLI respects `.gitignore` and `.avenignore`. Files excluded by either are never included in the report. The watcher does not execute your project's code, tests, or scripts.

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

At any point during a running session, you can check the current state and estimated payment with:

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

This shows the elapsed active time, the current rate, and an estimated payment based on tracked seconds so far.

**6. Stop the session and submit your report**

When you are ready to end a work period, run:

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

The CLI will:

1. Signal the background watcher to stop.
2. Calculate the final Git change statistics.
3. Ask for your **delivery statement** — a short written summary of what you worked on.
4. Display the complete work report for your review.
5. Ask whether you want to submit the report to the stream.

**Optional flags for `stop`:**

| Flag | Description |
| - | - |
| `--message <text>` | Provide your delivery statement inline, skipping the interactive prompt. |
| `--submit` | Submit the report immediately after preview without a second confirmation. |
| `--ended` | Mark this as the **final project session** — triggers delivery branch verification and requests settlement of the remaining escrow. |

```bash theme={null}
# Example: stop with an inline message and auto-submit
npx aven-stellar stop --message "Implemented the assigned validation changes" --submit

# Example: final project delivery
npx aven-stellar stop --ended
```

> [!WARNING]
>
> Use `--ended` only for the very last session of a project. It triggers settlement of all remaining unreserved escrow. All pending or reserved payments must be resolved before a final session can be submitted.

If submission fails (e.g. due to a network error), run `aven-stellar stop` again. The CLI retains the original stop timestamp and retries the exact same report — the delay is not counted as additional work time.

**7. Request employer review**

After the report is submitted, it appears under the **WORK SESSIONS** tab on the stream page. Navigate to the stream page in the Aven dashboard and click **Request Review** to notify your employer that the session is ready for approval.

Your employer will see the full report: active time, Git changes, your delivery statement, and the contract-calculated payment amount.

**8. Receive payment after approval**

Once your employer approves the session:

1. The stream contract calls `approve_withdrawal` and immediately executes `withdraw_approved`.
2. The exact payment amount is transferred to your Freighter wallet.
3. A permanent on-chain attestation is minted, linking the work record to your Stellar address.

The payment and attestation are visible on your profile at `/profile/[your-address]`.

***

## Managing multiple sessions

You can only have **one active session per repository** at a time. The `.aven/` directory stores a single session file for each repository root.

If you need to start a new session before the previous one was submitted:

1. Run `aven-stellar stop` to end the current session.
2. Review and submit (or discard) the report when prompted.
3. Run `aven-stellar start` to begin the next session.

> [!NOTE]
>
> If a session is in a `stopped` (unsubmitted) state, you cannot start a new one. Submit or discard the stopped session first.

***

## The `.aven/` directory

The CLI stores all local session state inside `.aven/` at the root of your repository:

| File | Contents |
| - | - |
| `session.json` | The active or stopped session record (timing, Git refs, watcher PID). |
| `report.json` | The last generated work report, saved locally before submission. |
| `config.json` | Your dashboard URL, stream ID, and authorization token. |

> [!WARNING]
>
> Do not commit the `.aven/` directory. It contains your scoped CLI authorization token. Add it to `.gitignore` if it is not already excluded. The CLI creates an `.avenignore` file with safe defaults automatically.

***

> [!TIP]
>
> Use `npx aven-stellar sessions` to list all sessions submitted for your stream, including their status (`Pending`, `Reserved`, `Approved`, `Disputed`).


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