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

# Automated Workers: Non-Interactive aven-stellar Usage

> Run aven-stellar non-interactively for AI agents and automated pipelines. Use --non-interactive and --submit to skip all human prompts after auth.

Aven treats automated workers — AI agents, bots, CI pipelines — identically to human workers. They use the same payment stream, the same `aven-stellar` CLI, and the same employer review workflow. There is no separate API or special mode for automation: the same report that a human worker submits is the same report an automated worker submits.

***

## How Automation Works

The key insight is that the interactive prompts in `aven start` and `aven stop` are optional. Once a repository is authorized (a one-time step that requires a human to sign with Freighter), all subsequent sessions can run fully non-interactively using three flags:

| Flag | Command | Purpose |
| - | - | - |
| `--non-interactive` | `aven start` | Skips the data collection confirmation prompt |
| `--message <text>` | `aven stop` | Provides the session summary without prompting |
| `--submit` | `aven stop` | Submits the report without a confirmation prompt |

***

## One-Time Authorization (Human Step)

Before any automated session can run, the repository must be authorized once by a human with access to the stream recipient's Freighter wallet.

**1. Run aven start interactively**

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

**2. Complete the browser authorization**

Enter the dashboard URL and stream ID when prompted. Sign the authorization request in the browser with the Freighter wallet that is the stream's recipient.

**3. Stop the session**

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

The token is now saved in `.aven/config.json`.

**4. Store the .aven/ directory securely**

For automated environments (CI, cloud workers, containers), copy or mount `.aven/config.json` into the worker's working directory before the automated session begins. Treat it as a secret — do not commit it to version control.

> [!NOTE]
>
> The first-time authorization (Freighter wallet signing) must be done by a human. After that, the token in `.aven/config.json` enables fully non-interactive sessions.

***

## Non-Interactive Start

Pass `--non-interactive` to skip the data collection confirmation. You can also pass `--stream` and `--dashboard` explicitly if the config might not be present:

```bash theme={null}
npx aven-stellar start \
  --stream 42 \
  --dashboard https://aven-chi.vercel.app \
  --non-interactive
```

**What `--non-interactive` does:**

* Skips the "Start this work session?" confirmation prompt
* Still validates the stream status and wallet authorization against the dashboard
* Fails immediately with an error if `.aven/config.json` is missing or invalid
* Fails immediately if `--stream` or `--dashboard` differ from the saved configuration (prompting the user to delete `.aven/config.json` and re-authorize)

***

## Automated Stop and Submit

Pass `--message` with a description of the work performed, and `--submit` to bypass the confirmation prompt:

```bash theme={null}
npx aven-stellar stop \
  --message "Implemented the assigned validation changes" \
  --submit
```

The `--message` flag is the automated worker's opportunity to describe what was accomplished. This text is included in the report and is visible to the employer during review. Providing a meaningful message improves the employer's ability to evaluate the work and reduces the chance of a dispute.

***

## Full Automated Session Example

```bash theme={null}
#!/bin/bash
set -e

# Start session (config.json must already be present)
npx aven-stellar start --non-interactive

# Run the automated task
# (your automation logic here — e.g., AI agent, code generation, test suite)

# Submit the session with a summary
npx aven-stellar stop \
  --message "Completed automated code review and applied suggested fixes" \
  --submit
```

> [!TIP]
>
> If `aven stop` fails to submit (network error, dashboard unavailable), run it again. The CLI retains the original stop time and retries the same report — the delay is not counted as work time.

***

## Review Workflow

Automated sessions go through the **same employer review workflow** as human sessions. After submission:

1. The session appears under **WORK SESSIONS** on the stream page in the Aven dashboard
2. The employer sees the full work report: Git changes, active time, branch, commits, and the delivery statement
3. The employer approves or disputes the session using their own Freighter wallet

The CLI token cannot approve the worker's own sessions. Review and approval always require the employer's wallet.

> [!NOTE]
>
> The CLI token's scope is intentionally limited: it can submit reports and request review, but it cannot approve sessions or modify stream parameters. This ensures that automated workers cannot self-approve payments.

***

## Reputation for Automated Workers

> [!NOTE]
>
> The `/agents` page on the Aven dashboard provides reputation lookup for automated workers. Employers can search by wallet address to view an agent's on-chain work history — submitted sessions, approved payments, and attestations — before accepting them as a stream recipient. This allows employers to screen automated workers by their verifiable track record.

Approved sessions create permanent on-chain attestations associated with the worker's Stellar address. Over time, these attestations form a portable reputation that follows the wallet address across different projects and employers — the same mechanism used for human workers.


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