Metadata-Version: 2.4
Name: general-augment-cli
Version: 0.5.5
Summary: CLI for General Augment, the agent backend for your app.
Project-URL: Homepage, https://generalaugment.com
Project-URL: Documentation, https://docs.generalaugment.com
Project-URL: Source, https://github.com/LunarVentures/general-augment-platform
Project-URL: Issues, https://github.com/LunarVentures/general-augment-platform/issues
Author: General Augment
License-Expression: MIT
Keywords: agent-backend,ai-agents,general-augment,llm,memory,tools
Requires-Python: >=3.12
Requires-Dist: click>=8.1.7
Requires-Dist: httpx>=0.27.0
Requires-Dist: jsonschema>=4.22.0
Requires-Dist: keyring<26,>=25.0.0
Requires-Dist: pydantic>=2.7.0
Requires-Dist: pyyaml>=6.0.0
Requires-Dist: rich>=13.7.0
Requires-Dist: typer<0.26,>=0.12.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# General Augment CLI

General Augment is the agent backend for your app.

`genaug` is its noun-first CLI for governed Project configuration and operations.

> The dashboard and CLI operate the same Project desired state. CLI mutations produce immutable
> Candidate releases; the dashboard provides human review and Live authority.

## Install

The package requires Python 3.12 or newer.

```bash
uv tool install general-augment-cli==0.5.5
pip install general-augment-cli==0.5.5
genaug --version
```

From this repository:

```bash
uv tool install --editable ./packages/cli
```

## Fastest Path

Run this from the authenticated app repository:

```bash
genaug auth login

genaug launch \
  --app-root . \
  --project-name "Commerce App" \
  --project-slug commerce-app \
  --issuer-url https://app.example.com \
  --jwks-url https://app.example.com/.well-known/jwks.json \
  --audience commerce-app \
  --user-id-claim sub \
  --callback-base-url https://app.example.com \
  --env-file .env.local \
  --wait
```

`launch` creates or links one Project, commits the framework-neutral app contract, creates one
reusable Candidate runtime key, writes it directly to an ignored server environment file, and
stores its paired `GENAUG_PROJECT_ID` beside it for fail-fast request isolation. It then verifies
the app-backend binding. It works for a new app, an existing app without an Agent, or an
app replacing another agent backend.

Then compose Agents from Project resources:

```bash
genaug capability import openapi orders \
  --spec ./orders.openapi.json \
  --operation listOrders=orders.read

genaug credential set orders-api --from-env ORDERS_API_KEY

genaug agent create support \
  --purpose "Help signed-in customers manage their orders" \
  --soul ./agents/support/SOUL.md \
  --skill ./skills/order-support/SKILL.md \
  --capability orders.read \
  --memory user-memory:read-write \
  --connection app-backend \
  --wait

genaug agent test support --user customer_123
genaug release promote <release-id>
```

Passing `--skill .../SKILL.md` captures that Skill's complete visible UTF-8 directory tree. Every
supporting file is fingerprinted into the Candidate and materialized unchanged for Hermes. Hidden
files are ignored, empty supporting placeholders are preserved, and symbolic links or nested
`SKILL.md` entrypoints are rejected so each Hermes-visible Skill remains explicitly granted.

Another Agent reuses the same capability, credential, memory namespace, connection, and Project
runtime key. None of those resources are installed a second time.

## Project State

The server-versioned desired-state head is authoritative. The repository contains its synchronized
working copy:

```text
genaug-agent.yaml
.genaug/
├── context.json              # gitignored Project binding and base revision
└── assets/                   # content-addressed local source assets
```

`genaug-agent.yaml` uses `apiVersion: genaug/v3`. It describes the Project identity contract,
memory namespaces, capabilities, credential requirements, connections, policy ceiling, source
assets, and every Agent.

The CLI resolves Project context in this order:

1. `--project <project>`;
2. repository-local `.genaug/context.json`;
3. the globally active Project selected by `genaug project use`.

If the dashboard advanced the remote head while the local source stayed clean, the CLI
fast-forwards. If both changed, it returns a semantic conflict and does not overwrite either side.

## One Mutation Path

Every governed mutation performs the same transaction:

```text
load Project head
  -> apply typed mutation
  -> validate references and permissions
  -> compile and compute semantic diff
  -> atomically persist revision + Candidate + plan + operation + audit + outbox
  -> reconcile and verify asynchronously
  -> return a stable receipt
```

Common options:

| Option | Behavior |
| --- | --- |
| `--project` | Override active Project resolution. |
| `--plan` | Validate and show the semantic diff with no local or remote writes. |
| `--draft` | Atomically update only the local v3 bundle. |
| `--json` | Return stable prompt-free machine output. |
| `--wait` | Follow operation events to an actionable terminal state. |

The default commits one Candidate remotely and then writes the server-normalized source locally.
An idempotent retry returns the same receipt; a no-op creates no revision or release.

Operational commands such as user memory correction, credentials, runs, jobs, usage, and audit are
directly audited. They do not create fake local drafts or Candidate releases.

## Command Tree

```text
genaug
├── auth login|logout|whoami
├── workspace create|list|use
│   └── member invite|list|update|remove
├── project create|list|show|use|update|export|transfer|delete
├── agent create|list|show|update|clone|delete|test
│   ├── soul show|set
│   ├── skill attach|detach
│   ├── capability grant|revoke
│   ├── memory grant|revoke
│   ├── model show|set
│   ├── limits show|set
│   ├── delegation add|list|remove
│   └── connect|disconnect
├── skill add|list|show|remove
├── capability import|register|list|show|test|remove
├── credential set|status|connect|rotate|remove
├── memory namespace create|list|update|remove
├── user list|show|link|unlink
│   └── memory list|search|correct|export|delete
├── connection list|show|test|disable
├── policy show|update
├── approval list|show|approve|deny|open
├── release plan|deploy|list|show|diff|promote|rollback
├── run list|show|watch|cancel|retry
├── job create|list|show|run|pause|resume|delete
├── eval create|list|run|show
├── usage show|export|move-starter-credit
├── budget show|set
├── audit list|export
├── key create|list|rotate|revoke
├── dashboard open
├── status
├── doctor
└── launch
```

There are no public plural aliases, top-level deploy/promote/rollback aliases, provider-specific
setup trees, or v1/v2 management commands.

Provider funding is operational policy, not Agent behavior. Select tenant-paid inference with
`genaug budget set --funding-mode byok`; select `free_sandbox`, `subscription_included`, or
`prepaid_payg` when General Augment should use its provider account and Project credits.

## Secrets and Live Authority

Secret values enter only through a named environment variable, stdin, or browser OAuth:

```bash
genaug credential set orders-api --from-env ORDERS_API_KEY
genaug credential rotate orders-api --from-stdin
genaug credential connect analytics-oauth
genaug key create --target candidate --env-file .env.local
```

Management OAuth material is stored in the OS keychain. Local YAML and config retain identifiers
and scopes, never raw credentials or runtime keys.

Developers may create, reconcile, and test Candidates. Workspace owners/admins may promote or roll
back Live. Terminal promotion requires a fresh interactive human session and typing the complete
release fingerprint. `--json`, service accounts, and API keys receive the dashboard review URL and
cannot silently promote.

## Machine Output

Use `--json` for coding agents and automation:

```bash
genaug agent create support ... --json
genaug status --json
genaug doctor --json
```

Responses include a versioned envelope or schema marker and never prompt. Stale source writes fail
with a semantic `409` conflict; the CLI never resolves that by last-write-wins.

## Development

From the repository root:

```bash
uv run --project packages/cli genaug --version

UV_CACHE_DIR=/private/tmp/ga-team2-uv-cache \
PYTHONPATH=packages/cli/src \
.team2/run test-target TESTS="packages/cli/tests -q"

UV_CACHE_DIR=/private/tmp/ga-team2-uv-cache \
mise x -- uv run mypy packages/cli/src
```

The complete public reference is
[`docs/public/CLI-REFERENCE.md`](../../docs/public/CLI-REFERENCE.md).
