Agent Reference

Quick-reference for AI coding assistants and automation scripts. Tested on 2026-03-30 against instructure-dap-client 2.2.0. For full documentation, see the individual command pages linked below.

---

Commands at a glance

Command	Purpose	Output	Docs
dap list	List available tables in a namespace	stdout, one name per line	list
dap schema	Download JSON schema for table(s)	<table>_schema_version_<N>.json file	schema
dap snapshot	Download full table data	gzipped files in job_<uuid>/	snapshot
dap incremental	Download changes since a timestamp	gzipped files in job_<uuid>/	incremental
dap initdb	Snapshot + persist to DB	database writes	initdb
dap syncdb	Incremental + persist to DB	database writes	syncdb
dap dropdb	Drop table(s) from DB	database writes	dropdb
dap listdb	List replicated tables in local DB	stdout (interactive) or JSON (non-interactive)	listdb

Scripting flags

Always use these flags when calling dap from scripts or agents:

dap --non-interactive --loglevel warning <command> [options]

• --non-interactive disables the rich console UI

• --loglevel warning suppresses info-level log lines from stderr

• --logformat json makes error logs machine-parseable

Record structure

All data (snapshot and incremental) uses the same record structure:

{
  "key": { "id": 1358 },
  "value": { "name": "Default Term", "created_at": "2024-04-18T08:19:36.120Z", "workflow_state": "active" },
  "meta": { "ts": "2026-02-09T20:27:52.099Z" }
}

• key — primary key, always present

• value — data columns, present on upserts

• meta.ts — CDC timestamp (ISO 8601, UTC)

• meta.action — "U" (upsert) or "D" (delete); absent in snapshot data, present in incremental data

Exit codes

Code	Meaning	Source
0	Success (including empty incremental results)	—
2	CLI usage error (missing flags, unknown options)	Click framework
5	API/operation error (bad table, bad namespace, auth failure, --since too old)	errno.EIO
78	Not implemented	errno.ENOSYS
89	Cancelled / keyboard interrupt	errno.ECANCELED

Error log format (--logformat json)

{
  "level": "ERROR",
  "message": "Operation snapshot failed. Reason: The table name 'nonexistent' specified in the request is not valid. <uuid>",
  "timestamp": "2026-03-30T12:40:09Z",
  "logger_name": "dap",
  "dap_namespace": "canvas",
  "dap_table": "nonexistent",
  "dap_client_id": "eu-west-1#..."
}

Typical workflow

# 1. Discover tables
dap --non-interactive --loglevel warning list --namespace canvas

# 2. Check schema
dap --non-interactive --loglevel warning schema --namespace canvas --table accounts --output-directory ./schemas

# 3. Full snapshot (first time)
dap --non-interactive --loglevel warning snapshot --namespace canvas --table accounts --format jsonl --output-directory ./data

# 4. Incremental updates (subsequent runs — use timestamp from last successful sync)
dap --non-interactive --loglevel warning incremental --namespace canvas --table accounts --since 2026-03-29T00:00:00Z --output-directory ./data

Known namespaces

canvas, canvas_logs, catalog, new_quizzes

Common gotchas

1. No --output json flag. This was v1 only. The list command outputs plain text; all other commands write to files.

2. --since requires timezone. Use Z or +HH:MM. Bare timestamps like 2024-01-01T00:00:00 are rejected.

3. --since too old. If the timestamp precedes the table's earliest available data, the API returns exit code 5 and advises re-snapshotting.

4. Empty incremental is not an error. Exit code 0, output file exists but is empty (0 bytes decompressed).

5. Files are always gzipped. Even with --format csv or --format tsv, output files have .gz extension.