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

​
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):
Global installation:
The CLI requires Node.js 20 or newer and must be run from inside a Git repository.
If you need to force npx to resolve the latest published version after an update, run:
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/.
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:
The CLI launches a lightweight background activity watcher that tracks active time and detects idle periods.Optional flags:
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.
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:
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:
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:
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.
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:
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.
Use npx aven-stellar sessions to list all sessions submitted for your stream, including their status (Pending, Reserved, Approved, Disputed).