Get Paid for Verified Work Using the aven-stellar CLI

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.

PrerequisitesBefore 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

Install the CLI

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

# Run any command directly — npx downloads the package on first use
npx aven-stellar start
npx aven-stellar stop
npx aven-stellar status

# Install once, then use the short alias from any terminal
npm install --global aven-stellar

aven start
aven stop
aven status

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.

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.

Open a terminal inside your project’s Git repository.
Run the start command:
npx aven-stellar start
When prompted, enter the Aven dashboard URL your employer shared (for example, https://aven-chi.vercel.app).
Enter the stream ID — a numeric identifier your employer can find on the stream page.
The CLI opens the /cli/authorize page in your browser.
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.

The CLI never receives, stores, or transmits your Stellar secret key. Authorization is entirely wallet-signed through Freighter in your browser.

Start a work session

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

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:

# 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

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.

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.

Check session status (optional)

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

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.

Stop and submit

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

npx aven-stellar stop

The CLI will:

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

Optional flags:

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

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.

Wait for employer review

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

Open the stream page and review your work report, including Git statistics, active time, changed files, and your delivery statement
Approve the session — the smart contract automatically reserves and releases the calculated payment to your wallet address
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.

npx aven-stellar stop --ended

When you pass --ended, the CLI:

Prompts you to select delivery branches — choose from your local branches or select all
Resolves the head commit of each selected branch
Verifies branch commits against the connected GitHub repository — branches that are not pushed will be flagged with a warning
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.

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

Complete reference for all aven-stellar commands and flags, including start, stop, status, and sessions.

Privacy and Safety

Learn exactly what the CLI collects, what it never touches, and how your wallet authorization is scoped and protected.

Freelancer Workflow

End-to-end walkthrough of a typical engagement — from receiving a stream invitation to final payment release.

Get Started

Core Concepts

Contract Architecture

Workflows

CLI Reference

Guides

Get Paid for Verified Work Using the aven-stellar CLI

Payment calculation

Final delivery sessions

Next steps

CLI Command Reference

Privacy and Safety

Freelancer Workflow

​Payment calculation

​Final delivery sessions

​Next steps

CLI Command Reference

Privacy and Safety

Freelancer Workflow

Payment calculation

Final delivery sessions

Next steps