Skip to main content

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.

archal twin continues to work as a legacy alias for every subcommand on this page. New code should prefer archal clone.

​
Usage

archal clone <subcommand>
Run archal clone with no subcommand to see the available twin catalog.

​
Subcommands

​
tools

List the MCP tools a twin exposes without booting a session. Useful for previewing surface area before starting a run. 
archal clone tools github
archal clone tools github --json

​
start

Start a persistent hosted twin session. 
archal clone start github jira
archal clone start --all
OptionDescription
--allStart all available twins
--seed <seeds...>Preload named seeds (e.g. --seed github:enterprise-repo stripe:small-business). Variadic.
--seed-file <path>Load a JSON or markdown seed file into the first twin after startup
--setup <text>Describe desired state in plain English (seeds the first twin)
--setup-file <path>Read setup description from a file
--name <name>Custom session name shown on the dashboard
--ttl-seconds <n>Request a longer session lifetime (capped server-side)
--freshBypass idempotency replay — always create a new session even if params match a recent one
Clone sessions stay alive for 30 minutes of inactivity, then auto-teardown. Use archal clone renew to extend.

​
status

Show the active session, worker health, and API base URLs. 
archal clone status
archal clone status --json

​
list

List all active hosted twin sessions for the current user. 
archal clone list
archal clone list --json

​
attach

Attach the local CLI to an existing hosted session. Useful when sharing a session between terminals. 
archal clone attach <session-id>

​
renew

Extend the active session lifetime. Defaults to 1 hour if no duration is given. 
archal clone renew
archal clone renew 7200

​
seed

Load state into a running twin. 
archal clone seed github enterprise-repo          # named seed
archal clone seed github --file seed.json  # JSON seed file

​
reset

Reset one or all twins to a clean state. 
archal clone reset github   # reset one twin
archal clone reset          # reset all twins in the session

​
stop

Tear down the active session and print usage stats. 
archal clone stop

​
Using the returned URLs

archal clone start prints API base URLs you can use directly in your code: 
import { Octokit } from '@octokit/rest';

const github = new Octokit({
  baseUrl: 'https://<session>.twins.archal.ai/github/api',
});

import stripe

stripe.api_key = "sk_test_fake"
stripe.api_base = "https://<session>.twins.archal.ai/stripe/api"
If you are calling those endpoints from curl, a Lambda, or a worker instead of the Archal CLI, use the dual-header pattern in Direct API access.