Skip to main content
aven-stellar is the official Node.js CLI for Aven — a Stellar-based protocol for funding work, measuring active delivery, and releasing exact payments. It records active coding time and Git change metadata for an existing Aven payment stream, then generates a structured, reviewable report that can be submitted to the Aven dashboard for employer approval. The CLI is designed around a single principle: workers deserve a verifiable record of what changed during a work period without giving up privacy. File contents, keystrokes, and wallet secrets never leave the machine.

​
Key Facts

​
What aven-stellar Does

  • Starts and stops work sessions — records session start time, active vs. idle time, and Git state
  • Tracks active time — a lightweight background watcher detects file change events to distinguish active coding from idle time
  • Generates reports — captures branch, commits since session start, relative changed file paths, and diff statistics
  • Calculates payment amounts — multiplies verified active seconds by the stream’s on-chain rate, capped by unreserved escrow
  • Submits to the Aven dashboard — sends the structured report to the stream page for employer review and approval

​
What aven-stellar Does NOT Do

  • Does not upload source files or file contents
  • Does not record keystrokes, mouse movements, or screenshots
  • Does not request or store your Stellar secret key
  • Does not execute project code, tests, or scripts
  • Does not install project dependencies
  • Does not read files excluded by .gitignore or .avenignore

​
Commands Overview

​
Quick Example

On first run, start asks for your dashboard URL and stream ID, then opens your browser to authorize with your Freighter wallet. On subsequent runs, it reads the saved configuration from .aven/config.json and launches a background activity watcher immediately. When you run stop, the CLI calculates the payment amount from your recorded active time, displays the full report for review, and asks before submitting to the dashboard.

​
Explore the CLI

Installation

Install aven-stellar via npx or npm global install. Set up your first authorization.

Commands

Complete reference for all commands and flags: start, stop, status, and sessions.

Privacy & Safety

Exactly what data the CLI records, what it never accesses, and how local state is managed.

Automated Workers

Run aven-stellar non-interactively for AI agents and automated pipelines.