Skip to main content
Requirements before you start:
  • Node.js 20 or newer — check with node --version
  • npm — bundled with Node.js
  • A Git repository — the CLI must be run from inside a repository with at least one commit
  • Freighter wallet — configured for Stellar testnet (freighter.app)
  • An Aven stream — where your wallet address is the designated recipient
No installation required. npx downloads and runs aven-stellar automatically, always resolving the latest published version:
For production use, pin to a specific version to guarantee reproducible behavior:

​
Option 2: Global Install

Install aven-stellar once and use it across all your projects:
After a global install, both the aven and aven-stellar command aliases are available on your PATH:

​
Force the Latest Version

When testing a newly published release, tell npx to bypass its cache and resolve the current package from the registry:

​
First-Time Authorization

The first time you run aven start in a repository, the CLI guides you through a one-time setup to connect to your Aven stream and authorize your wallet.
1

Open a terminal inside your Git repository

Navigate to the project directory where your work will happen. The CLI requires at least one existing commit.
2

Run aven start

3

Enter the Aven dashboard URL

When prompted, provide the Aven dashboard URL. For the hosted instance:
For local development, use http://localhost:3000.
4

Enter your stream ID

Enter the stream ID provided by your employer (digits only). This identifies the payment agreement you are working against.
5

Authorize in the browser

The CLI opens /cli/authorize in your default browser. The Aven dashboard will prompt you to sign an authorization message with your Freighter wallet.
The CLI never receives your wallet secret key. It only receives a scoped, short-lived authorization token after you sign the request in your browser.
6

Authorization complete

After signing, the browser confirms success and the CLI continues. The authorization token is saved to .aven/config.json for all future sessions in this repository.

​
The .aven/ Directory

After first-time setup, the CLI creates a .aven/ directory in your repository root. This directory holds local session state and should not be committed. The .aven/ directory itself is created with mode 0700 (owner access only), and each file inside is created with mode 0600 (owner read/write only).
Add .aven/ to your .gitignore. The CLI automatically creates .avenignore to protect sensitive paths, but .aven/config.json contains your authorization token and must not be committed to version control.
The CLI also creates .avenignore in your repository root on first aven start. This file works like .gitignore and controls which paths are excluded from work reports. See the Privacy & Safety page for details.

​
Re-Authorization

If your dashboard URL or stream ID changes, you need to re-authorize: Option A — Delete and re-run:
Option B — Pass flags to trigger a reset prompt:
If you pass --non-interactive alongside a changed --dashboard or --stream flag, the CLI exits with an error instead of prompting. Delete .aven/config.json manually before running the automated workflow.