[integration hardening plan](docs/2026-08-20-integration-hardening-and-staging-readiness-recommendations.md).

The typed settings, safe feature profile, and redacted readiness command are in

[docs/runtime-configuration.md](docs/runtime-configuration.md).

Repository creation, one-time GitHub import, and the terminal client are

documented in the [OpenAgents CLI guide](docs/openagents-cli/index.md).

## Capability status

- Voice session, transcript, usage, recording, and operator-projection domains.

- Issues, comments, labels, milestones, projects, public status, changelog, and

  bounded source-browsing surfaces.

- GitHub-backed repository namespaces, private and public repository creation,

  one-time GitHub import, Git smart HTTP, and the Effect TypeScript CLI.

- Git HTTP, push receipts, promotion targets, build receipts, and local BEAM

  deployment primitives, including transactional direct loading, two-way

  relups, and provider-neutral rolling replacement.

- Direct BEAM loading, relup installation, rolling replacement, and boot

  convergence require isolated three-node staging proof before they can be

  enabled outside a disposable environment.

- The self-hosted forge is being hardened, but GitHub remains the canonical Git

  remote until the proof-gated cutover in ADR 0007.

- The self-hosted forge is being hardened. GitHub remains the canonical remote

  for the OpenAgents platform repository until the proof-gated cutover in ADR

  0007; newly created hosted repositories use OpenAgents as their source of

  truth.

### Planned or blocked on hardening

- Repository-backed tenant isolation for every issue and project record.

- Staging qualification and release of repository creation, GitHub import, and

  the OpenAgents CLI.

- Separate web and distributed staging lanes, a full regression matrix,

  failure-injection drills, and a 48-hour soak.

- Any production rollout. Production remains explicitly out of scope until the

# OpenAgents CLI command reference

The `openagents` command manages authentication and hosted repositories.

```text

openagents <subcommand> [flags]

```

Run `openagents <command> --help` for the reference installed with your CLI

version.

## Global flags

| Flag | Description |

| --- | --- |

| `--profile production\|staging\|local` | Select a named API profile. |

| `--api-url ORIGIN` | Use a custom HTTPS or loopback API origin. |

| `--json` | Write one machine-readable JSON value. |

| `--no-color` | Disable ANSI output. |

| `--help`, `-h` | Show help. |

| `--version`, `-v` | Show the CLI version. |

| `--completions bash\|zsh\|fish\|sh` | Print a shell completion script. |

Place shared flags before the subcommand, for example:

```sh

openagents --profile staging --json repo list

```

Setting `NO_COLOR` also disables ANSI output.

## Authentication commands

| Command | Description |

| --- | --- |

| `openagents auth login` | Start browser-assisted device authorization and store the token. |

| `openagents auth login --token-stdin` | Read and store a token from standard input. |

| `openagents auth token-stdin` | Read and store a token from standard input. |

| `openagents auth status` | Show the selected API, account, namespaces, expiry, and helper state. |

| `openagents auth logout` | Remove the stored token for the selected API origin. |

| `openagents auth setup-git --local` | Configure the current Git repository. |

| `openagents auth setup-git --global --yes` | Configure global Git settings with explicit confirmation. |

`auth git-credential` is an internal Git helper endpoint. Do not invoke it

directly.

## Repository commands

### `repo create`

```text

openagents repo create [flags] <name-or-namespace/name>

```

| Flag | Description |

| --- | --- |

| `--description TEXT` | Set the repository description. |

| `--public` | Create a public repository. |

| `--private` | Create a private repository, which is the default. |

| `--default-branch NAME` | Set the initial default branch. The default is `main`. |

| `--wait-timeout SECONDS` | Wait for provisioning. The default is `300`; `0` does not wait. |

| `--source DIRECTORY` | Attach the new repository to a Git worktree. |

| `--remote NAME` | Set the remote name used with `--source`. The default is `origin`. |

The command creates the server repository before it configures a local remote.

It never pushes automatically.

### `repo import`

```text

openagents repo import [flags] <github-owner/repository>

```

| Flag | Description |

| --- | --- |

| `--name NAME` | Override the destination repository name. |

| `--namespace OWNER` | State the matching eligible GitHub owner. |

| `--public` | Create a public destination. |

| `--private` | Create a private destination, which is the default. |

| `--wait-timeout SECONDS` | Wait for import. The default is `300`; `0` does not wait. |

This command performs one import. It does not start synchronization.

### `repo list`

```text

openagents repo list [--namespace OWNER] [--limit 1..100] [--after CURSOR]

```

The default limit is `30`. When more results exist, human output prints the

next opaque cursor and JSON output returns it as `next_cursor`.

### `repo view`

```text

openagents repo view [OWNER/REPOSITORY]

openagents repo view --repo OWNER/REPOSITORY

```

When you omit the repository, the CLI infers it from an exact OpenAgents

`origin` remote on the selected API origin.

### `repo clone`

```text

openagents repo clone [OWNER/REPOSITORY] [DIRECTORY]

openagents repo clone --repo OWNER/REPOSITORY [DIRECTORY]

```

The CLI retrieves the clone URL from the API and starts standard Git.

## JSON and noninteractive use

With `--json`, stdout contains machine-readable output. Human progress and

errors do not contaminate a successful JSON response. Responses never include

an API token or token digest.

In a noninteractive process:

- Set `OPENAGENTS_TOKEN` or provide an existing credential-store entry.

- Pass every ambiguous value as an argument or flag.

- Do not use browser login or global Git-helper setup.

- Handle `SIGINT` and `SIGTERM` as exit code `130`. The CLI cancels in-flight

  HTTP work and terminates its child Git process.

## Exit codes

| Code | Meaning |

| --- | --- |

| `0` | Success. |

| `1` | Git, output, or unclassified operational failure. |

| `2` | Usage, configuration, or validation error. |

| `3` | Authentication, authorization, or credential-store failure. |

| `4` | Repository or API resource not found. |

| `5` | Conflict, such as an existing repository name. |

| `6` | Network, server, transport, or API-contract failure. |

| `7` | Provisioning or import failure or timeout. |

| `130` | Interrupted by `SIGINT` or `SIGTERM`. |

## Commands not included

This release does not provide `repo delete`, `repo mirror`, pull-request,

ruleset, SSH-key, generic API, or self-update commands. Use only commands shown

by the installed version's `--help` output.

# Create an OpenAgents repository

Create an empty repository from the web interface or with the OpenAgents CLI.

If the code already exists on GitHub, use a [one-time GitHub

import](import-github.md) instead.

## Create a repository in the browser

1. Sign in to OpenAgents with GitHub.

2. Open `/repositories`.

3. Select **New repository**.

4. Choose your GitHub user or an eligible GitHub organization namespace.

5. Enter a name and optional description.

6. Choose **Private** or **Public**. Private is the default.

7. Enter the default branch. The default value is `main`.

8. Select **Create repository**.

The repository can briefly show a provisioning state. Push instructions appear

after durable provisioning finishes.

## Create a repository with the CLI

Create a private repository in your GitHub user namespace:

```sh

openagents repo create my-project

```

Create a public repository in an eligible organization namespace:

```sh

openagents repo create OpenAgentsInc/my-project --public

```

Set a description and default branch:

```sh

openagents repo create my-project \

  --description "Example repository" \

  --default-branch trunk

```

The CLI waits up to 300 seconds for provisioning by default. Pass

`--wait-timeout 0` to return after the server accepts the durable request. The

repository continues provisioning on the server.

## Attach an existing local project

Create the remote repository and attach it to an existing Git worktree:

```sh

openagents repo create my-project --source .

```

The CLI verifies the Git worktree, adds the server-provided clone URL as the

`origin` remote, and prints the next push command. It does not push

automatically.

Choose a different remote name when `origin` already belongs to another host:

```sh

openagents repo create my-project --source . --remote openagents

git push -u openagents HEAD

```

The CLI refuses to overwrite an existing remote that points to a different

URL. If remote attachment fails, the remote repository still exists.

## Push the first commit

For an existing local project:

```sh

openagents auth setup-git --local

git push -u origin HEAD

```

To start from an empty directory:

```sh

git init my-project

cd my-project

git branch -M main

git remote add origin https://openagents.com/git/OWNER/my-project.git

# Add files, then commit them.

openagents auth setup-git --local

git push -u origin main

```

Prefer the clone URL returned by the browser or CLI instead of constructing it

yourself.

## Names and visibility

Repository names are case-insensitive and normalize to lowercase. A name:

- Contains 1 through 64 ASCII characters.

- Starts with a letter or digit.

- Uses letters, digits, hyphens, underscores, and qualifying dots.

- Cannot use a reserved OpenAgents route or Git-internal name.

- Must be unique within the namespace.

A private repository requires an authorized OpenAgents membership. A public

repository permits anonymous Git reads. The creator becomes the repository

owner. OpenAgents does not automatically copy every GitHub organization member

into the repository.

## Organization repositories

OpenAgents uses GitHub to verify organization identity and membership. You need

an active GitHub organization administrator membership to create a repository

in that organization during the first release.

Custom OpenAgents namespaces, repository transfer, rename, archive, and delete

are not available yet.

## Next steps

- [Clone, push, and pull](git.md)

- [Import a GitHub repository](import-github.md)

- [CLI command reference](command-reference.md)

# Clone, push, and pull

OpenAgents serves Git smart HTTP at an HTTPS URL returned by the repository API

and web interface. Standard Git performs clone, fetch, push, and pull.

## Clone with the CLI

```sh

openagents repo clone OWNER/REPOSITORY

```

Choose a destination directory:

```sh

openagents repo clone OWNER/REPOSITORY ./local-directory

```

The command uses the server-provided clone URL and invokes Git without putting

the token in the URL or process arguments. For the clone operation, it scopes

the OpenAgents credential helper to the selected API origin.

## Clone with Git

Copy the HTTPS URL from the repository page, then run:

```sh

git clone https://openagents.com/git/OWNER/REPOSITORY.git

```

Public repositories support anonymous clone and fetch. Private repositories

require an authorized credential.

Before you use standard Git with a private repository, configure the helper:

```sh

cd existing-worktree

openagents auth setup-git --local

```

Use global setup only when you want every local repository to use the helper

for the selected OpenAgents origin:

```sh

openagents auth setup-git --global --yes

```

## Push and pull

After you configure the helper, use standard Git commands:

```sh

git push -u origin main

git fetch origin

git pull --ff-only

```

Repository owners, maintainers, and contributors can push. Viewers can clone

and fetch but cannot push. Token authorization is checked again for each Git

request, so revoking or expiring a token takes effect without changing the

remote URL.

## Infer a repository from `origin`

From a worktree whose `origin` is an exact OpenAgents clone URL:

```sh

openagents repo view

```

The CLI accepts only `/git/OWNER/REPOSITORY.git` on the selected API origin. It

does not infer authority from an arbitrary URL that resembles a repository

path. Override inference explicitly when needed:

```sh

openagents repo view --repo OWNER/REPOSITORY

openagents repo clone -R OWNER/REPOSITORY

```

## Authentication safety

The credential helper:

- Returns credentials only for the exact selected OpenAgents origin.

- Rejects username, port, path, or protocol mismatches.

- Reads `OPENAGENTS_TOKEN` or the operating-system credential store.

- Never writes a token into the Git remote URL.

- Never logs complete credential-helper input.

OpenAgents uses HTTPS in this release. SSH remotes and SSH-key management are

not available yet.

## Next steps

- [Install and authenticate the CLI](install.md)

- [CLI command reference](command-reference.md)

# Import a GitHub repository

Import copies one accepted GitHub snapshot into a new OpenAgents repository.

It does not create a mirror or continue synchronizing with GitHub.

## Prerequisites

You need:

- An OpenAgents account connected to GitHub.

- A current GitHub connection with the `repo` and `read:org` grants.

- Read access to the source GitHub repository.

- An eligible destination namespace that matches the GitHub source owner.

- An active GitHub organization administrator membership for an organization

  destination.

If your existing GitHub connection lacks the required grants, reconnect it

before importing.

## Import in the browser

1. Sign in to OpenAgents with GitHub.

2. Open `/repositories`.

3. Select **Import from GitHub**.

4. Choose a repository from the bounded GitHub repository list.

5. Confirm the matching destination namespace.

6. Keep the source name or enter a different destination repository name.

7. Choose **Private** or **Public**. Private is the default, even when the

   GitHub source is public.

8. Review any Git LFS warning.

9. Select **Import repository**.

The import page shows the accepted snapshot and bounded lifecycle state. It

does not expose raw Git output or a GitHub token.

## Import with the CLI

Import a repository into its matching namespace:

```sh

openagents repo import OpenAgentsInc/example

```

Choose a different destination name:

```sh

openagents repo import OpenAgentsInc/example --name example-copy

```

Create a public destination explicitly:

```sh

openagents repo import OpenAgentsInc/example --public

```

You can state the matching organization explicitly:

```sh

openagents repo import OpenAgentsInc/example --namespace OpenAgentsInc

```

The `--namespace` value must match the GitHub source owner in this release. You

cannot import `SOURCE/repository` directly into an unrelated namespace.

The CLI waits up to 300 seconds by default. Pass `--wait-timeout 0` to return

after the server accepts the durable import. A client timeout does not cancel

the server-side import.

## What the import copies

| Copied | Not copied |

| --- | --- |

| Git commit and object history reachable from accepted refs | GitHub Issues |

| `refs/heads/*` branches | Pull requests and reviews |

| `refs/tags/*` tags | Actions workflows, runs, and secrets |

| The source default branch | Releases and repository settings |

| Submodule pointer commits | Wikis and Git LFS objects |

OpenAgents freezes the accepted branch and tag map before copying data. It

verifies that same ref snapshot before marking the repository ready. A GitHub

commit created after acceptance is not part of the import.

Git LFS pointer files remain in Git history, but OpenAgents does not copy the

referenced LFS objects. Download or migrate those objects separately before

you rely on the imported repository.

## After the import

OpenAgents becomes the source of truth for the new repository. Later GitHub

changes do not flow to OpenAgents, and OpenAgents pushes do not flow back to

GitHub. The repository page labels the result as imported once and records the

source and accepted snapshot.

Clone and work with the destination as a normal OpenAgents repository:

```sh

openagents repo clone OpenAgentsInc/example

cd example

git push

```

## Next steps

- [Clone, push, and pull](git.md)

- [CLI command reference](command-reference.md)

# OpenAgents CLI

The OpenAgents CLI (`openagents`) manages OpenAgents-hosted Git repositories

from a terminal. It uses the same repository API as the OpenAgents web

interface and leaves Git data transfer to standard Git.

The CLI is implemented and locally verified. The production release remains

gated while OpenAgents completes staging qualification.

## What you can do

The first release lets you:

- Sign in through your GitHub-backed OpenAgents account.

- Create a private or public repository in your GitHub user namespace.

- Create a repository in an eligible GitHub organization namespace.

- Import a GitHub repository as a one-time copy.

- List and inspect repositories that you can access.

- Clone repositories and configure Git authentication.

- Push, pull, and fetch through Git smart HTTP.

- Use JSON output and stable exit codes in scripts and agents.

Pull requests, repository deletion, continuous GitHub mirroring, SSH transport,

rulesets, and self-update are not part of this release.

## Namespaces and access

OpenAgents uses GitHub namespaces in the first release. When you sign in with

GitHub, your OpenAgents user namespace has the same login as your GitHub user.

Eligible organization namespaces use the same GitHub organization login. You

do not claim a separate OpenAgents namespace.

OpenAgents keys namespaces to GitHub's immutable account IDs. If a GitHub login

changes, OpenAgents can update the displayed login without changing the

repository's identity.

Creating or importing in an organization requires an active GitHub organization

membership with the organization administrator role. OpenAgents adds the

creator as the repository owner. It does not automatically grant access to

every member of the GitHub organization.

## Visibility and privacy

New repositories are private unless you explicitly select public visibility.

A public repository permits anonymous Git reads. A private repository is

visible only to authorized OpenAgents members, and unauthorized requests do

not reveal whether it exists.

OpenAgents stores GitHub access tokens on the server and never sends them to

the browser or the CLI. The CLI stores its OpenAgents API token in an approved

operating-system credential store, or reads it from `OPENAGENTS_TOKEN` for a

single environment.

Repository creation does not grant deployment or operator authority. The

deployment allowlist remains separate from hosted repositories.

## Manage repositories in the browser

After you sign in, open `/repositories` to see the repositories that you can

access.

- Select **New repository** to create an empty repository.

- Select **Import from GitHub** to copy one GitHub repository.

- Open a repository to see its clone URL, lifecycle state, Issues, Projects,

  code, and import receipt when applicable.

## Next steps

- [Install the CLI](install.md)

- [Create a repository](create-repository.md)

- [Import a GitHub repository](import-github.md)

- [Clone, push, and pull](git.md)

- [CLI command reference](command-reference.md)

# Install the OpenAgents CLI

The npm package is `@openagentsinc/cli`, and it installs the `openagents`

command. The package requires Node.js 24 or later.

The production npm release remains gated. The install command below applies

after the package is published.

## Install with npm

```sh

npm install --global @openagentsinc/cli

```

Verify the installed version:

```sh

openagents --version

```

To update after a release, install the latest npm package again:

```sh

npm install --global @openagentsinc/cli@latest

```

The CLI does not include an `openagents update` command.

## Run the CLI from source

From the root of the `openagents` monorepo:

```sh

pnpm --filter @openagentsinc/cli run build

node packages/openagents-cli/dist/main.js --version

```

## Sign in

Start the browser-assisted device authorization flow:

```sh

openagents auth login

```

The CLI prints a verification URL and user code, opens the URL when your

operating system supports it, and waits for approval. Complete the flow with

the GitHub account connected to OpenAgents.

The CLI stores the resulting `oa_pat_` token for the selected API origin:

- On macOS, it uses Keychain through the `security` command.

- On Linux, it uses Secret Service through `secret-tool`.

- On an unsupported platform or a host without an admitted credential store,

  it fails closed. Use `OPENAGENTS_TOKEN` without storing the token.

Check the selected account, namespaces, token source, expiry, and Git helper

state:

```sh

openagents auth status

```

Remove the stored credential for the selected API origin:

```sh

openagents auth logout

```

## Use a token without a browser

For an interactive token import, pass the token through standard input. The

CLI never accepts a token as a command-line argument.

```sh

openagents auth token-stdin

```

`openagents auth login --token-stdin` provides the same behavior.

For an agent or CI process, set the token in the environment for the process:

```sh

OPENAGENTS_TOKEN="oa_pat_..." openagents --json repo list

```

Do not put a token in a Git URL, configuration file, shell history, or process

argument.

## Select an API profile

The CLI uses the production profile by default.

| Profile | API origin |

| --- | --- |

| `production` | `https://openagents.com` |

| `staging` | `https://staging.openagents.com` |

| `local` | `http://localhost:4000` |

Select a named profile or a custom origin before the command:

```sh

openagents --profile staging auth status

openagents --profile local repo list

openagents --api-url https://forge.example.com repo list

```

Custom origins must use HTTPS. The CLI permits HTTP only for loopback hosts.

An API URL must be an origin without a path, query, fragment, username, or

password.

The CLI resolves endpoint settings in this order:

1. `--api-url`

2. `--profile`

3. `OPENAGENTS_API_URL`

4. `OPENAGENTS_PROFILE`

5. `api_url` in `~/.config/openagents/config.json`

6. `profile` in `~/.config/openagents/config.json`

7. The production profile

You can set `OPENAGENTS_CONFIG_PATH` to read a different configuration file.

The file accepts `profile` or `api_url` and never stores credentials.

```json

{

  "profile": "local"

}

```

## Configure Git authentication

Configure only the current Git repository:

```sh

openagents auth setup-git --local

```

Global setup requires an interactive terminal and explicit confirmation:

```sh

openagents auth setup-git --global --yes

```

The helper is scoped to the selected OpenAgents origin. It refuses unrelated

hosts and never places a token in a Git URL or process argument.

## Next steps

- [Create a repository](create-repository.md)

- [Clone, push, and pull](git.md)

- [CLI command reference](command-reference.md)