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

# Manual quickstart

> Use the Archal CLI and a curated state sample without coding-agent setup.

Use this path when you prefer to inspect and run each command yourself.

## 1. Install and sign in

```bash theme={null}
npm install --global archal@0.11.0
node --version
archal --version
archal login
archal doctor
```

The GA CLI requires Node.js 22 or newer.

Keep the stored control-plane credential out of source code and test subprocesses.

## 2. Choose a starting state

```bash theme={null}
archal environment describe github
archal sample list github
archal sample show github.small-project.v1
archal sample show github.small-project.v1 --raw > github-small-project.json
archal state validate github github-small-project.json
```

`sample show --raw` verifies the packaged artifact hash before printing it.

## 3. Create a sandbox

```bash theme={null}
archal session create github \
  --state github=github-small-project.json
```

The command waits for readiness and prints the sandbox as a session response.
Save that response securely. It contains the `sessionId`, provider URL, and a
scoped credential that expires with the sandbox.

## 4. Call the environment

Use `environments.github.apiBaseUrl` as the provider base URL. Apply every
header in `environments.github.credentials.headers` to provider requests.
Do not substitute the Archal workspace key. The data plane rejects it.

The TypeScript client applies these returned headers automatically:

```ts theme={null}
const response = await archal.callEnvironment(session.sessionId, 'github', {
  method: 'GET',
  path: '/user',
});
```

## 5. Inspect, reset, and destroy

```bash theme={null}
archal state get <session-id> github > github-before-response.json
jq '.state' github-before-response.json > github-before.json

# Run a provider-shaped mutation, then compare against the explicit snapshot.
archal state diff <session-id> github --before github-before.json

archal session reset <session-id>
archal session destroy <session-id>
```

For current JSON environments, reset restores the loaded sample because it
became the sandbox baseline. Supabase has a separate canonical reset expectation
documented on its environment page.
Destroy promptly when the test ends. Expiration is a recovery mechanism, not
the normal cleanup path.