Skip to main content

​
Usage

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

​
Subcommands

​
start

Start a persistent hosted twin session. 
archal twin start github jira
archal twin start --all
OptionDescription
--allStart all available twins
--seed <twin:name>Preload a named seed (e.g. github:enterprise-repo). Repeatable.
--seed-file <path>Load a JSON 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
--ttl-seconds <n>Request a longer session lifetime (capped server-side)
Sessions stay alive for 30 minutes of inactivity, then auto-teardown. Use archal twin renew to extend.

​
status

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

​
list

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

​
attach

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

​
renew

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

​
seed

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

​
reset

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

​
stop

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

​
Using the returned URLs

archal twin 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.