Skip to main content
archal autoloop connects a harness repo to trace evidence. Hosted database sources are registered with Archal and processed by hosted workers. Local trace directories run a local loop and write artifacts under .archal/autoloop/.

​
Usage

archal autoloop [trace-dir] --repo <dir> [options]
trace-dir is required for local file-backed autoloops. Omit it when using --source postgres or --source supabase.

​
Required options

OptionDescription
--repo <dir>Harness repository to autoloop
For hosted database sources, also set:
OptionDescription
--source <provider>postgres or supabase
--database-url-env <name>Environment variable containing the database URL
--database-url-secret-ref <ref>External secret reference for the database URL
Use exactly one of --database-url-env or --database-url-secret-ref.

​
Source options

OptionDefaultDescription
--source-name <name>Stable display name for the read-only trace source
--source-id <uuid>Optional hosted source UUID; non-UUID values are treated as --source-name for compatibility
--trace-table <table>ai_tracesTrace table
--span-table <table>ai_spansChild span table
--trace-id-column <column>idTrace id column
--span-id-column <column>idSpan id column
--span-trace-id-column <column>trace_idSpan-to-trace foreign key column
--parent-span-id-column <column>Parent span column
--trace-updated-at-column <column>updated_atTrace update cursor column
--span-updated-at-column <column>updated_atSpan update cursor column
--trace-created-at-column <column>Trace creation cursor column
--span-created-at-column <column>Span creation cursor column
--cursor-mode <mode>updated_at_idupdated_at_id or created_at_id
--traces-watermark-at <iso>Initial trace timestamp cursor
--traces-watermark-id <id>Initial trace id cursor
--spans-watermark-at <iso>Initial span timestamp cursor
--spans-watermark-id <id>Initial span id cursor

​
Filters

OptionDescription
--source-workspace-id <id...>Import only these source workspace ids
--source-status <status...>Import only these source statuses
--source-trace-group <group...>Import only these trace groups
--source-agent-id <id...>Import only these agent ids
--source-limit <rows>Maximum rows to scan per poll
--source-metadata <key=value...>Non-secret labels stored with the source

​
Execution policy

--execution-policy observe|grade|reproduce|fix
Default: fix
PolicyRuns through
observeimport
gradeimport and grade
reproduceimport, grade, seed, and reproduce
fixfull loop, including GitHub issue or PR creation

​
Validation

Use --check to validate prerequisites without registering a hosted source or starting a local loop: 
archal autoloop \
  --repo . \
  --source supabase \
  --database-url-env TRACE_DATABASE_URL \
  --check

​
Examples

Register a hosted Supabase source: 
export TRACE_DATABASE_URL='postgres://readonly:...'

archal autoloop \
  --repo . \
  --source supabase \
  --database-url-env TRACE_DATABASE_URL \
  --source-name prod-agent-traces
Register a hosted Postgres source with custom mapping: 
archal autoloop \
  --repo . \
  --source postgres \
  --database-url-env TRACE_DATABASE_URL \
  --trace-table public.ai_traces \
  --span-table public.ai_spans \
  --trace-id-column id \
  --span-id-column id \
  --span-trace-id-column trace_id \
  --parent-span-id-column parent_span_id
Use a secret reference instead of a local database URL: 
archal autoloop \
  --repo . \
  --source postgres \
  --database-url-secret-ref aws-secretsmanager://customer/prod-agent-traces
Watch a local directory and stop after reproduction: 
archal autoloop ./prod-traces --repo . --execution-policy reproduce
Stop a local file-backed autoloop: 
archal detach ./prod-traces --repo .
archal detach applies to local file-backed autoloops. Hosted database sources are managed by hosted Autoloop workers; local detach does not disable them.

​
Output

Hosted database source registration prints: 
Registered hosted trace source: prod-agent-traces
Source id: 11111111-1111-4111-8111-111111111111
Repository: acme/agent
Provider: supabase
Archal will poll this read-only source from the hosted autoloop worker.
Local file-backed autoloops print the trace directory, repo, resolved GitHub repository, execution policy, artifact directories, loop process id, and log path.

​
Local artifacts

Local file-backed autoloops write: 
.archal/autoloop/
  autoloops.json
  runs.jsonl
  raw/
  grades/
  seeds/
  runs/
  fixes/
  failed/
  logs/
Hosted database sources expose phase information in workspace Autoloop state. Local autoloop-status reads the repo-local ledger for file-backed autoloops only. For terminal-first handoffs, pair local artifacts with: 
archal autoloop-status --repo .
archal autoloop-reprocess --repo . <trace-id>
Use autoloop-status to summarize terminal trace jobs. Use autoloop-reprocess after fixing the missing evidence, credential, mapping, harness, or GitHub blocker that caused a trace job to stop.

​
Exit behavior

archal autoloop exits non-zero when prerequisites fail, source options are invalid, database credentials are missing or malformed, the repo cannot be resolved to GitHub where required, or hosted registration fails.

​
See also