> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aient.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Aient CLI

> Authenticate per project, offload a local workspace, and operate isolated Aient sandboxes.

# Aient CLI

The `aient` command runs local development work in isolated remote sandboxes. This guide documents Aient CLI 0.7.0, available as a static binary for macOS and Linux on Intel and Arm.

<CardGroup cols={2}>
  <Card title="Authentication and projects" icon="key" href="/ai-tools/cli/authentication">
    Keep separate customer sessions and bind each checkout to the intended Aient profile.
  </Card>

  <Card title="Environment secrets" icon="lock" href="/ai-tools/cli/environment-secrets">
    Set or replace an encrypted environment secret without exposing its value in a command line.
  </Card>

  <Card title="Run and synchronise" icon="rotate" href="/ai-tools/cli/run-and-sync">
    Run a local Git worktree remotely or synchronise its exact state into a retained sandbox.
  </Card>

  <Card title="Retained sandboxes" icon="box" href="/ai-tools/cli/retained-sandboxes">
    Create, inspect, reuse, enter, and delete sandboxes.
  </Card>

  <Card title="Executions and files" icon="terminal" href="/ai-tools/cli/executions-and-files">
    Observe live commands and transfer explicit files.
  </Card>
</CardGroup>

## Install and verify

Download the current release from the [Aient CLI release repository](https://github.com/aient-ai/aient-cli/releases/latest). Follow the repository's [installation and verification guide](https://github.com/aient-ai/aient-cli#install-on-macos-or-linux) before placing the binary on your `PATH`.

Each release includes static archives, SHA-256 checksums, SPDX SBOMs, Sigstore verification bundles, and SLSA provenance. GitHub-generated source archives are documentation only; they are not verified Aient CLI release artifacts.

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
aient version
aient auth login
aient auth status
```

## Quick start

From a local Git checkout:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
aient sandbox run --environment development -- pnpm test
```

With `--environment`, the CLI synchronizes the current workspace by default. It shows the organisation, resolved environment, inferred or selected repository, and brokered GitHub capabilities before creating the sandbox.

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
Organisation: Example Engineering
Environment:  development
Repository:   example/widget (inferred from origin)
GitHub access: branch push, pull requests
```

The local checkout is the workspace source. A configured Git remote is only a repository selector. The Aient service verifies membership, environment policy, repository ownership, and the active GitHub App installation before granting any provider operation.

<Note>
  An organisation administrator must enable customer CLI workspaces for the selected environment. If it is disabled, the command fails before sandbox creation with `HTTP 403: development environment is not enabled for CLI workloads`.
</Note>

## Choose a workflow

Use `sandbox run` for a disposable command:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
aient sandbox run --environment development -- go test ./...
```

Use `--keep` when you want to retain the created, environment-bound sandbox:

```sh theme={"theme":{"light":"github-light","dark":"github-dark"}}
aient sandbox run \
  --name laptop-offload \
  --keep \
  --environment development \
  --repository example/widget \
  -- true
aient sandbox list --environment development
aient --timeout 15m sandbox exec laptop-offload \
  --environment development \
  --repository example/widget \
  --workdir /workspace/repo -- pnpm test
aient sandbox delete laptop-offload
```

In 0.7.0, an environment-bound customer sandbox can be reused only through selector-bearing `sandbox exec` and `sandbox execution` commands, found with `sandbox list --environment`, and removed by its owner with `sandbox delete`. `sandbox sync`, `files`, `shell`, `status`, `wait`, and `logs` cannot reopen that bound sandbox. To transfer changed local state, delete it and start a fresh `sandbox run --keep`.

Commands without `--environment` operate without environment or repository capabilities.

## Current limitations

The commands documented in this section are the surface shipped in Aient CLI 0.7.0.

* Commands cannot be deliberately detached. `sandbox execution attach` can follow an already-known live execution, but output is not retained for replay.
* `sandbox shell` always opens a new shell. Shell reattachment and shell history are unavailable.

See [Current limits and troubleshooting](/ai-tools/cli/troubleshooting) for recovery guidance and common errors.