Manual quickstart

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

node --version
npm install --global archal@0.11.3
archal --version
archal login
archal doctor

The GA CLI requires Node.js 22 or newer. Check the runtime before installing so an unsupported Node version does not consume setup time or leave a partial npm cache entry. On Windows PowerShell, use npx.cmd when an execution policy blocks the npx.ps1 shim. This applies to one-off npx commands; the global archal commands below are unchanged. Keep the stored control-plane credential out of source code and test subprocesses.

2. Choose a starting state

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

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:

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

5. Inspect, reset, and destroy

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.

​1. Install and sign in

​2. Choose a starting state

​3. Create a sandbox

​4. Call the environment

​5. Inspect, reset, and destroy

1. Install and sign in

2. Choose a starting state

3. Create a sandbox

4. Call the environment

5. Inspect, reset, and destroy