> ## 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.

# Quickstart

> Install the Archal CLI, add a tiny harness that calls your agent, and run your first scored agent task against a hosted GitHub clone in minutes.

Use this guide when you already have agent code that can be called from a
script. If you do not have an agent yet, start with a small function that reads
the task and prints a final answer, then replace it with your real agent later.

Archal runs your agent against realistic service clones and scores what changed.
The shortest path is:

1. Install the CLI in your agent repo.
2. Add a tiny harness that calls your real agent.
3. Run one task against a clone.

## What you'll prove

Your first run asks your agent to inspect a seeded GitHub clone and summarize
its open issues - read-only, so production GitHub is untouched. Archal starts
the clone, runs your agent, collects the trace, and prints a satisfaction score.
This matches the `scenarios/first-run.md` that `archal init` scaffolds; once it
passes, swap in write tasks like creating or closing issues.

## Install

Run this inside your agent's repository:

```bash theme={null}
npx archal init
```

`init` detects your agent platform, adds `archal` as a dev dependency, copies
helper skills into the repo, and creates `.archal.json`, `.archal/harness.mjs`,
and `scenarios/first-run.md`. Requires Node.js 20.20 or later (the version
`archal` declares in `engines`). If your agent supports skills, start with
`archal-agent`; it can help wire the starter harness to your agent.

<Note>
  Run `init` inside a folder with a `package.json`. With no `package.json`, it
  installs the skills and config but **skips** adding the `archal` dev dependency
  and tells you to install it globally (`npm i -g archal`) or run `npm init` first.
</Note>

<Tip>
  Skipping `init` is supported, but then you need to create the harness and
  `.archal.json` yourself.
</Tip>

## Log in

```bash theme={null}
npx archal login
```

This opens a browser window and saves CLI credentials locally. Already signed
in? Run `archal whoami` to confirm your workspace and skip this step.

For CI, SSH, or any headless environment, set a workspace API key
(`archal_ws_...`) as `ARCHAL_TOKEN`:

```bash theme={null}
export ARCHAL_TOKEN=archal_ws_<your-key>
```

Create one with `archal workspace api-key create ci-runner` from a logged-in
owner/admin session, or from the dashboard under **Settings > API Keys**. Copy
it once and store it as a secret. See [archal workspace](/cli/workspace) for
list/revoke commands.

A workspace API key is already bound to one workspace. If you use a user token
and belong to more than one workspace, set `ARCHAL_WORKSPACE_ID` to target a
specific one:

```bash theme={null}
export ARCHAL_WORKSPACE_ID=<workspace-id>
```

For local development, `archal login` (browser OAuth) is the easiest path.

## Add a harness

Archal needs a command it can run without opening your app UI. `archal init`
creates `./.archal/harness.mjs` for you. Edit it so `runAgent()` calls your
real agent:

```js ./.archal/harness.mjs theme={null}
const task = process.env.AGENT_TASK;
if (!task) {
  console.error('Missing AGENT_TASK');
  process.exit(1);
}

// Call the same code your CLI or product calls.
const result = await runMyAgent({ task });
const text = typeof result === 'string' ? result : JSON.stringify(result);
console.log(JSON.stringify({ text }));
```

<Tip>
  No agent yet? Copy the [minimal clone-calling harness](/guides/first-harness#minimal-clone-calling-harness-no-agent-framework)

  * it calls the GitHub clone's REST API directly (no agent framework or model
    key) and produces a real score against the scaffolded scenario.
</Tip>

Check it before using clones:

```bash theme={null}
AGENT_TASK="Reply with OK and do not use tools." node ./.archal/harness.mjs
```

The harness should call real SDKs and real service domains, such as Octokit
calling `api.github.com`. Archal routes supported service traffic to clones
during the run.

Add `.archal.json` so Archal knows how to start it:

```json theme={null}
{
  "agent": {
    "command": "node",
    "args": ["./.archal/harness.mjs"]
  },
  "clones": ["github"],
  "scenarios": ["scenarios/first-run.md"]
}
```

## Run your first scored task

`init` already wrote `.archal.json` (clone + scenario + harness). If your
harness calls normal service domains like `api.github.com`, use Docker or
sandbox mode so Archal can route DNS/TLS to clones:

```bash theme={null}
npx archal run --docker
```

You should see Archal start a GitHub clone, run your agent, collect the trace,
and print a score.

<Note>
  When `.archal.json` lists a scenario, that scenario runs. To try an ad-hoc
  inline task instead, run in a folder without a configured scenario:
  `npx archal run --task "List recent issues" --harness ./.archal/harness.mjs --clone github`.
</Note>

Bare `npx archal run` is only appropriate when the harness calls explicit clone
URLs, such as the minimal clone-calling harness linked above.

## Write a scenario

Inline tasks are good for smoke tests. For repeatable checks, write a scenario:

```markdown theme={null}
# Close Stale Issues

## Setup
A GitHub repository with 10 open issues. 4 of them have no activity in 90 days.

## Prompt
Close all issues with no activity in the last 90 days. Add a comment explaining why.

## Success Criteria
- [D] Exactly 4 issues are closed
- [D] All closed issues have a new comment
- [P] Each closing comment explains the reason for closure

## Config
clones: github
timeout: 90
```

Run it once, then run it several times when you care about consistency:

```bash theme={null}
npx archal run scenarios/close-stale-issues.md --docker
npx archal run scenarios/close-stale-issues.md --docker --runs 5
```

## What to read next

* [Run scenarios against your agent](/guides/run-with-agent) to adapt a real app or agent repo.
* [Writing scenarios](/guides/writing-scenarios) to turn one-off tasks into repeatable tests.
* [Clone sessions](/guides/clone-sessions) to inspect stable clone endpoints manually.