> For the complete documentation index, see [llms.txt](https://developerdocs.instructure.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developerdocs.instructure.com/services/dap/dap-cli-readme/dap-cli-reference/agent-reference.md).

# 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](/services/dap/dap-cli-readme/dap-cli-reference/dap-cli-reference-list.md)               |
| `dap schema`      | Download JSON schema for table(s)    | `<table>_schema_version_<N>.json` file         | [schema](/services/dap/dap-cli-readme/dap-cli-reference/dap-cli-reference-schema.md)           |
| `dap snapshot`    | Download full table data             | gzipped files in `job_<uuid>/`                 | [snapshot](/services/dap/dap-cli-readme/dap-cli-reference/dap-cli-reference-snapshot.md)       |
| `dap incremental` | Download changes since a timestamp   | gzipped files in `job_<uuid>/`                 | [incremental](/services/dap/dap-cli-readme/dap-cli-reference/dap-cli-reference-incremental.md) |
| `dap initdb`      | Snapshot + persist to DB             | database writes                                | [initdb](/services/dap/dap-cli-readme/dap-cli-reference/dap-cli-reference-initdb.md)           |
| `dap syncdb`      | Incremental + persist to DB          | database writes                                | [syncdb](/services/dap/dap-cli-readme/dap-cli-reference/dap-cli-reference-syncdb.md)           |
| `dap dropdb`      | Drop table(s) from DB                | database writes                                | [dropdb](/services/dap/dap-cli-readme/dap-cli-reference/dap-cli-reference-dropdb.md)           |
| `dap listdb`      | List replicated tables in local DB   | stdout (interactive) or JSON (non-interactive) | [listdb](/services/dap/dap-cli-readme/dap-cli-reference/dap-cli-reference-listdb.md)           |

## Scripting flags

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

```sh
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:

```json
{
  "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)

```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

```sh
# 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.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developerdocs.instructure.com/services/dap/dap-cli-readme/dap-cli-reference/agent-reference.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.