> 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-getting-started.md).

# Getting Started

A step-by-step guide for IT admins, analysts, and non-technical users.

## 1. Get API Client ID and Secret

To access the DAP API, you will need a Client ID and Secret. These are generated via the Instructure Identity Services.

#### Steps:

1. Log into [Instructure Identity Services](https://identity.instructure.com).
2. Select your institution from the drop-down menu and log in.
3. Once authorized, navigate to the dashboard and click **Add New Key**.
4. Enter a name for the key and set the expiration time.
5. Copy the **Client ID** and **Secret** when they appear. **Note:** These are displayed only once. If you lose them, you will need to generate new ones.

## 2. Install DAP CLI on Your Computer

The DAP CLI tool allows you to interact with the Canvas Data 2 API. Installation steps differ slightly depending on your operating system.

#### For Mac:

1. Install Xcode Developer Tools:

   ```sh
   xcode-select --install
   ```
2. Download and install Python 3.11+ from [here](https://www.python.org/downloads/), then check the installed version:

   ```sh
   python3 --version
   ```
3. Check that PIP is available (it is installed with Python by default):

   ```sh
   pip3 --version
   ```
4. Install the DAP CLI tool with PostgreSQL support:

   ```sh
   pip3 install "instructure-dap-client[postgresql]"
   ```

   Replace `postgresql` with the extra for your database — see [Database Extras](#database-extras) below.

#### For Windows:

1. Install Python 3.11+ from [here](https://www.python.org/downloads/windows/).
2. Install the DAP CLI tool with PostgreSQL support using the Windows command prompt:

   ```sh
   pip3 install "instructure-dap-client[postgresql]"
   ```

   Replace `postgresql` with the extra for your database — see [Database Extras](#database-extras) below.

### Database Extras

The database drivers are **not** installed by default. To use the database commands ([`dap initdb`](/services/dap/dap-cli-readme/dap-cli-reference/dap-cli-reference-initdb.md), [`dap syncdb`](/services/dap/dap-cli-readme/dap-cli-reference/dap-cli-reference-syncdb.md), [`dap dropdb`](/services/dap/dap-cli-readme/dap-cli-reference/dap-cli-reference-dropdb.md) and [`dap listdb`](/services/dap/dap-cli-readme/dap-cli-reference/dap-cli-reference-listdb.md)), you must install the DAP CLI with the *extra* that matches your database. The name of the extra is the same as the prefix of your [connection string](#4-work-with-databases):

| Database             | Extra        | Install command                                     |
| -------------------- | ------------ | --------------------------------------------------- |
| PostgreSQL           | `postgresql` | `pip3 install "instructure-dap-client[postgresql]"` |
| MySQL                | `mysql`      | `pip3 install "instructure-dap-client[mysql]"`      |
| Microsoft SQL Server | `mssql`      | `pip3 install "instructure-dap-client[mssql]"`      |

Install several extras at once by separating them with commas:

```sh
pip3 install "instructure-dap-client[postgresql,mysql]"
```

{% hint style="info" %}
The quotes around the package name are required in most shells, which would otherwise interpret the square brackets themselves.
{% endhint %}

If you only export data to files with [`dap snapshot`](/services/dap/dap-cli-readme/dap-cli-reference/dap-cli-reference-snapshot.md) or [`dap incremental`](/services/dap/dap-cli-readme/dap-cli-reference/dap-cli-reference-incremental.md), no extra is needed:

```sh
pip3 install instructure-dap-client
```

#### Additional Requirement for Microsoft SQL Server

The `mssql` extra builds on [pyodbc](https://pypi.org/project/pyodbc/), which needs an ODBC driver installed on the operating system, separately from the Python packages. Install the [Microsoft ODBC Driver for SQL Server](https://learn.microsoft.com/en-us/sql/connect/odbc/download-odbc-driver-for-sql-server) for your platform **before** installing the extra. On MacOS and Linux the driver also requires `unixODBC`, which `pyodbc` links against; without it, `pip3 install "instructure-dap-client[mssql]"` may fail to build.

### If You Missed Installing an Extra

If the extra for your database is missing, the DAP CLI cannot synchronize data with that database, and the database commands fail with an error message similar to the following:

```
ERROR - missing dependency: `asyncpg`; required by the `postgresql` extra
```

The message names both the missing package and the extra that provides it. To fix it, install the DAP CLI again with that extra:

```sh
pip3 install "instructure-dap-client[postgresql]"
```

## 3. Store Client Credentials in Environment Variables

For secure access to the API, it's recommended to store your credentials as environment variables. This prevents sensitive information from being exposed in command-line arguments.

#### MacOS/Linux:

1. Open Terminal and run the following commands, replacing placeholders with your actual Client ID and Secret:

   ```sh
   export DAP_CLIENT_ID='your_canvas_data_client_id'
   export DAP_CLIENT_SECRET='your_canvas_data_secret'
   ```
2. Restart Terminal for changes to take effect.

#### Windows:

Follow this [guide to setting environment variables](https://www.computerhope.com/issues/ch000549.htm) or use the `set` command in the Windows command line:

```sh
set DAP_CLIENT_ID=your_canvas_data_client_id
set DAP_CLIENT_SECRET=your_canvas_data_secret
```

Unless you set environment variables, you need to pass Client ID and Secret to the dap command explicitly:

```sh
dap --client-id=us-east-1#0c59cade-...-2ac120002 --client-secret=xdEC0lI...4X4QBOhM incremental --namespace canvas --table accounts --since 2022-07-13T09:30:00+02:00
```

## 4. Work with Databases

DAP CLI allows you to interact with PostgreSQL, MySQL or MSSQL databases. You will need the connection string of your database for DAP to function correctly.

#### Connection String Format:

```
protocol://username:password@host:port/database_name
```

#### Examples:

```
postgresql://user:password@host:5432/mydatabase
mysql://user:password@host:3306/mydatabase
mssql://user:password@host:1433/mydatabase
```

### Store Connection String in Environment Variables

#### MacOS/Linux:

1. Open Terminal and run the following commands, replacing placeholders with your actual Client ID and Secret:

   ```sh
   export DAP_CONNECTION_STRING=postgresql://user:password@localhost:5432/mydatabase
   ```
2. Restart Terminal for changes to take effect.

#### Windows:

Follow this [guide to setting environment variables](https://www.computerhope.com/issues/ch000549.htm) or use the `set` command in the Windows command line:

```sh
set DAP_CONNECTION_STRING=postgresql://user:password@localhost:5432/mydatabase
```

### Obtain Full Snapshots of Tables

Use the [`dap initdb`](/services/dap/dap-cli-readme/dap-cli-reference/dap-cli-reference-initdb.md) command to download full snapshots of tables and store them in your database.

#### Command:

```sh
dap initdb --connection-string postgresql://user:password@localhost/mydb --namespace canvas --table accounts,users
```

{% hint style="warning" %}
Regular use of snapshots is not recommended, as they are resource-intensive for the API and costly to process on the client side.
{% endhint %}

### Synchronize Data of Tables

After obtaining snapshots, keep your database updated with the [`dap syncdb`](/services/dap/dap-cli-readme/dap-cli-reference/dap-cli-reference-syncdb.md) command. This ensures incremental changes are applied to your tables.

#### Command:

```sh
dap syncdb --connection-string postgresql://user:password@localhost/mydb --namespace canvas --table accounts,users
```

## 5. Export Data

You can export data using either the snapshot or incremental methods, depending on your use case.

### Snapshot Export

Use [`dap snapshot`](/services/dap/dap-cli-readme/dap-cli-reference/dap-cli-reference-snapshot.md) command to download a full copy of tables at a point in time.

#### Command:

```sh
dap snapshot --namespace canvas --table accounts --format jsonl --output-directory ./data
```

{% hint style="warning" %}
Regular use of snapshots is not recommended, as they are resource-intensive for the API and costly to process on the client side.
{% endhint %}

#### Output structure

Snapshot data is written as gzipped files inside a `job_<uuid>/` subdirectory of the output directory:

```
./data/job_9783c06d-00c1-431e-acec-9eee41c8ca1e/
  part-00000-a5f7a08d-4d2e-4674-910b-5557f8b56e5a-c000.json.gz
```

Each decompressed line in JSONL format is a JSON object with `key`, `value`, and `meta` fields:

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

### Incremental Export

The [`dap incremental`](/services/dap/dap-cli-readme/dap-cli-reference/dap-cli-reference-incremental.md) command captures only the data that has changed since your last export.

#### Command:

```sh
dap incremental --namespace canvas --table accounts --since 2024-11-01T00:00:00Z --output-directory ./data
```

The `--since` timestamp must include a timezone (e.g. `Z` for UTC or `+02:00`). The output structure is the same as for snapshots. If there are no changes in the given time range, the output file will be empty but the command exits with code `0`.


---

# 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-getting-started.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.