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 attach 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/attach/.
Usage
archal attach [trace-dir] --repo <dir> [options]
trace-dir is required for local file-backed attachments. Omit it when using
--source postgres or --source supabase.
Required options
| Option | Description |
|---|
--repo <dir> | Harness repository to attach |
| Option | Description |
|---|
--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 |
--database-url-env or --database-url-secret-ref.
Source options
| Option | Default | Description |
|---|
--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_traces | Trace table |
--span-table <table> | ai_spans | Child span table |
--trace-id-column <column> | id | Trace id column |
--span-id-column <column> | id | Span id column |
--span-trace-id-column <column> | trace_id | Span-to-trace foreign key column |
--parent-span-id-column <column> | | Parent span column |
--trace-updated-at-column <column> | updated_at | Trace update cursor column |
--span-updated-at-column <column> | updated_at | Span 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_id | updated_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
| Option | Description |
|---|
--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
fix
| Policy | Runs through |
|---|
observe | import |
grade | import and grade |
reproduce | import, grade, seed, and reproduce |
fix | full loop, including GitHub issue or PR creation |
Validation
Use --check to validate prerequisites without registering a hosted source or
starting a local loop:
archal attach \
--repo . \
--source supabase \
--database-url-env TRACE_DATABASE_URL \
--check
Examples
Register a hosted Supabase source:
export TRACE_DATABASE_URL='postgres://readonly:...'
archal attach \
--repo . \
--source supabase \
--database-url-env TRACE_DATABASE_URL \
--source-name prod-agent-traces
archal attach \
--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
archal attach \
--repo . \
--source postgres \
--database-url-secret-ref aws-secretsmanager://customer/prod-agent-traces
archal attach ./prod-traces --repo . --execution-policy reproduce
archal detach ./prod-traces --repo .
archal detach applies to local file-backed attachments. Hosted database
sources are managed from the dashboard.
Output
Hosted database source registration prints:
Attached 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 attach worker.
Local artifacts
Local file-backed attachments write:
.archal/attach/
attachments.json
runs.jsonl
raw/
grades/
seeds/
runs/
fixes/
failed/
logs/
Exit behavior
archal attach 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
