# archal

Stateful testing environments for AI agents and integration tests.

Archal creates isolated testing environments for the external APIs in its
catalog through one workspace key. Load explicit state, call provider-shaped
endpoints, inspect or reset state, then destroy the session.

## Install

```bash
npm install archal
```

The package includes the TypeScript client and the `archal` CLI.

## TypeScript client

```ts
import { ArchalEnvironmentClient } from 'archal';

const archal = new ArchalEnvironmentClient({
  apiKey: process.env.ARCHAL_API_KEY!,
});

const session = await archal.createSession(
  {
    environments: ['github'],
    initialState: {
      github: {
        format: 'json',
        value: {
          users: [{ id: 1, login: 'octocat' }],
          repos: [],
        },
      },
    },
  },
  { idempotencyKey: 'github-contract-test' },
);

try {
  const response = await archal.callEnvironment(session.sessionId, 'github', {
    method: 'POST',
    path: '/user/repos',
    body: { name: 'checkout-eval', private: true },
  });

  console.log(response.status, response.data);
} finally {
  await archal.destroySession(session.sessionId);
}
```

`createSession` waits for readiness by default and attempts cleanup if readiness
fails. For latency-sensitive orchestration, use `startSession(...)` and then
`awaitSessionReady(sessionId)`. Creates automatically carry an idempotency key,
so transient control-plane retries cannot create duplicate sessions.

## CLI

```bash
export ARCHAL_API_KEY=archal_ws_<your-key>

archal environment list
archal session create github supabase \
  --state github=github-state.json \
  --state supabase=supabase.sql
archal session create github --detach
archal session wait <session-id>
archal state get <session-id> github
archal state load <session-id> github github-state.json
archal session reset <session-id>
archal session destroy <session-id> --detach
archal session wait <session-id> --until destroyed
archal sample list github
archal sample show github.small-project.v1 --raw
```

Connect a coding agent directly to the hosted lifecycle MCP endpoint:

```text
URL: https://archal.ai/api/mcp
Authorization: Bearer archal_ws_<your-key>
```

For clients that only support local stdio, run `archal mcp`.

## Usage billing

The $20 one-time trial does not require a card. When those credits are used, a
workspace owner or admin can enable usage billing with:

```bash
archal workspace billing setup
```

The command prints a Stripe Checkout URL when payment details are needed. Open
the URL in a browser, finish setup, then run the command again. When it reports
that usage billing is already configured, retry the session command that was
blocked.

Workspace API keys can start this idempotent setup flow, but they cannot open
the billing portal, cancel billing, or make one-time purchases. Those account
changes require an authenticated user credential.

## Authentication

Create a key in the Archal dashboard. The workspace key authenticates lifecycle
calls. Session responses include provider-shaped connection credentials scoped
to exactly one session and environment; the client applies those credentials
without forwarding the workspace key to provider calls.

Do not provide real provider credentials. Archal strips caller-supplied provider
authorization and injects a credential scoped to the session.

## Documentation

See [docs.archal.ai](https://docs.archal.ai) for state contracts, lifecycle
semantics, CLI commands, MCP tools, limits, and the OpenAPI reference.