> 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. For full documentation, see the individual command pages linked below.

## Required configuration

Set each value with an environment variable or a global command-line option. If you use both, the option wins.

| Environment variable | Global option     | Purpose                                                                                                                                                                    |
| -------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `DAP_API_URL`        | `--base-url`      | Base URL of your [regional API Gateway](https://developerdocs.instructure.com/services/dap/dap-cli-readme/dap-cli-security.md#regional-api-base-url). Required, no default |
| `DAP_CLIENT_ID`      | `--client-id`     | Client ID from the Instructure Identity Service                                                                                                                            |
| `DAP_CLIENT_SECRET`  | `--client-secret` | Client secret for that key                                                                                                                                                 |

Global options go before the command: `dap --base-url <url> --client-id <id> --client-secret <secret> list namespaces`. `dropdb` needs none of these, because it never calls the DAP API.

An API key is restricted to a set of tables it may read; a command that reads data from any other table fails. `dap schema` and `dap list` are not restricted by table. See [Table access](https://developerdocs.instructure.com/services/dap/dap-cli-readme/dap-cli-security.md#table-access).

***

## Commands at a glance

| Command               | Purpose                                | Output                                         | Docs                                                                                                                                |
| --------------------- | -------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `dap list namespaces` | List namespaces available for querying | stdout, one name per line                      | [list](https://developerdocs.instructure.com/services/dap/dap-cli-readme/dap-cli-reference/dap-cli-reference-list.md)               |
| `dap list tables`     | List available tables in a namespace   | stdout, one name per line                      | [list](https://developerdocs.instructure.com/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](https://developerdocs.instructure.com/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](https://developerdocs.instructure.com/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](https://developerdocs.instructure.com/services/dap/dap-cli-readme/dap-cli-reference/dap-cli-reference-incremental.md) |
| `dap initdb`          | Snapshot + persist to DB               | database writes                                | [initdb](https://developerdocs.instructure.com/services/dap/dap-cli-readme/dap-cli-reference/dap-cli-reference-initdb.md)           |
| `dap syncdb`          | Incremental + persist to DB            | database writes                                | [syncdb](https://developerdocs.instructure.com/services/dap/dap-cli-readme/dap-cli-reference/dap-cli-reference-syncdb.md)           |
| `dap dropdb`          | Drop table(s) from DB                  | database writes                                | [dropdb](https://developerdocs.instructure.com/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](https://developerdocs.instructure.com/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": "<id>"
}
```

## Typical workflow

```sh
# 1. Discover namespaces and tables
dap --non-interactive --loglevel warning list namespaces
dap --non-interactive --loglevel warning list tables --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. **`dap list` is a command group.** Use `dap list tables --namespace <ns>` or `dap list namespaces`; `dap list --namespace <ns>` is not valid.
2. **`DAP_API_URL` is required.** There is no default base URL; commands that call the DAP API fail without it. The [regional base URL](https://developerdocs.instructure.com/services/dap/dap-cli-readme/dap-cli-security.md#regional-api-base-url) is based on the Canvas region.
3. **A table the key may not read fails.** With several tables, the rest still run and the command exits non-zero.
4. **`dap list` output is not an access list.** It returns every namespace and table regardless of table access, so a name appearing there does not mean the key can read it.
5. **No `--output json` flag.** The `list` commands output plain text; all other commands write to files.
6. **`--since` requires timezone.** Use `Z` or `+HH:MM`. Bare timestamps like `2024-01-01T00:00:00` are rejected.
7. **`--since` too old.** If the timestamp precedes the table's earliest available data, the API returns exit code 5 and advises re-snapshotting.
8. **Empty incremental is not an error.** Exit code 0, output file exists but is empty (0 bytes decompressed).
9. **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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
