Command reference

Run pda --help for the list of commands, and pda <command> --help for the flags of one command. Run pda --version to print the version.

Command	What it does
`pda init`	Create a new project folder.
`pda debug`	Test connections to databases and models.
`pda sync`	Write table docs and other context into the project.
`pda chat`	Run the Polaris web app locally.
`pda test`	Run the project’s tests.
`pda deploy`	Upload the project to a Polaris server.
`pda login` and `pda logout`	Sign the CLI in to and out of a Polaris server.
`pda reset-password`	Reset a local user’s password.
`pda skills`	Install and manage skills for coding agents.
`pda migrate`	Export Metabase and Tableau content for Polaris.
`pda docs`	Open this documentation.

The CLI loads a .env file from the current directory when it starts.

`pda init`

Creates a project folder with pda_config.yaml, RULES.md, .pdaignore and the standard folders. Run interactively, it asks for a database, a model provider and Git repositories.

pda init                    # interactive
pda init -n my-project      # name the project and folder
pda init -y                 # no prompts, use defaults

Flag	Default	What it does
`-n`, `--name`		Project name, also used as the folder name.
`-f`, `--force`	off	Initialize again even if the folder exists.
`-y`, `--yes`, `--no-tty`	off	Run without prompts, for scripts and agents. With an existing `pda_config.yaml`, it only creates the folders. Without one and without `--name`, it initializes the current folder.

If pda_config.yaml already exists in the current folder, pda init checks it and offers to update it. After writing the config, it installs missing extras and runs pda debug.

`pda debug`

Tests the connection to every database and model provider in pda_config.yaml. It prints one table for databases and one for providers, with the available models.

pda debug

No flags. A warning that a configured model is “not in provider list” is expected for Bedrock inference profile ids that start with us..

`pda sync`

Writes context from your sources into the project folder, then renders *.j2 templates. See Synchronization.

pda sync
pda sync -p databases -t 4
pda sync -p databases:epigenomics -s "main.tcga_*"

Flag	Default	What it does
`-p`, `--provider`, `--providers`	all	Providers to sync: `notion`, `confluence`, `obsidian`, `repositories`, `databases`, `semantics`. Use `provider:name` for one connection, such as `databases:my-db`. Repeat the flag for several.
`-t`, `--threads`	`threads` in the config, or 1	Number of worker threads.
`-s`, `--select`		Sync only these `schema` or `schema.table` patterns (globs allowed), and keep the docs of other tables. Databases only.
`--no-render-templates`	off	Skip rendering `*.j2` templates.

Provider aliases: db, dbs and database for databases; repo, repos and repository for repositories; wiki for confluence; semantic, semantic_layer, semantic-layer and sl for semantics.

pda sync exits with code 1 if any provider or template fails.

`pda chat`

Runs the Polaris web app locally for the project in the current folder, and opens it in your browser at http://localhost:5005. The first account you create becomes the admin.

AWS_PROFILE=<your-profile> pda chat

Flag	Default	What it does
`-p`, `--port`	`SERVER_PORT`, or 5005	Port for the web app (1024 to 65535).
`--fastapi-port`	`FASTAPI_PORT`, or 8005	Port for the internal API server. Must differ from `--port`.
`--ngrok`	off	Open a public ngrok tunnel to the local app, for example to test Slack. Needs an ngrok account.
`--sandbox`	off	Download the runtime for running code in a local sandbox. Needed once.

pda chat needs the bundled server binary. See Run Polaris locally.

`pda test`

Runs the tests in tests/ against a running Polaris server. pda test and pda test run are the same. See Tests.

pda test
pda test -m bedrock:us.anthropic.claude-sonnet-5-5 -t 4 -k 3
BACKEND_URL=https://epigenomics.polaris.aws.grail.com pda test -u you@example.com

Flag	Default	What it does
`-m`, `--model`	`test.models` in the config	Model to test, as `provider:model_id`. Repeat to compare models.
`-t`, `--threads`	`test.threads`, or 1	Tests to run at the same time.
`-k`, `--k`	`test.k`, or 1	Runs per test, for pass@k and pass^k.
`-s`, `--select`	all	Tests to run, by name, file name or subfolder. Separate several with commas.
`-u`, `--username`	`PDA_USERNAME`	Email to sign in with.
`--password`	`PDA_PASSWORD`	Password to sign in with.
`--api-key`	`PDA_API_KEY`	Organization API key, instead of signing in.

Without credentials, the CLI uses the session from pda login, or opens a browser to sign in. The server URL comes from BACKEND_URL and defaults to http://localhost:5005.

`pda test server`

Starts a local web page to browse test results from tests/outputs/.

Flag	Default	What it does
`-p`, `--port`	8765	Port for the results page.
`--no-open`	off	Do not open the browser.

`pda deploy`

Uploads the project folder to a Polaris server, creating or replacing the project. See Deploy context.

pda deploy https://polaris.example.com --api-key "$PDA_API_KEY"

Argument or flag	Default	What it does
`URL`	required	The Polaris server URL.
`-k`, `--api-key`	required	Organization API key.
`-p`, `--path`	current folder	The project folder to upload.

`pda login`

Signs the CLI in to a Polaris server through your browser, and stores the session for pda test.

pda login --backend-url https://epigenomics.polaris.aws.grail.com

Flag	Default	What it does
`--backend-url`	`BACKEND_URL`, or `http://localhost:5005`	The Polaris server to sign in to.

`pda logout`

Signs out, revokes the stored session, and deletes it locally. Takes the same --backend-url flag as pda login.

`pda reset-password`

Resets the password of a user in a local Polaris (the one pda chat runs). The user must choose a new password at their next sign-in.

pda reset-password someone@example.com

Argument	What it is
`EMAIL`	The user’s email.

On a shared deployment, admins reset passwords in the web app instead. See Users and roles.

`pda skills`

Installs and manages skills for coding agents such as Claude Code and Codex. It passes every argument to npx skills, so it needs Node.js 18 or newer.

pda skills list
pda skills add <source>
pda skills update
pda skills remove <name>

See Skills for coding agents.

`pda migrate`

Exports content from other BI tools so Polaris can recreate it as charts and stories. The migrate-metabase and migrate-tableau-workbook skills use these commands.

`pda migrate metabase`

Subcommand	What it does
`configure`	Asks for the Metabase URL and API key, and saves them in `pda_config.yaml`.
`dashboard SOURCES...`	Exports dashboards, by numeric id or URL.
`question SOURCES...`	Exports saved questions, by numeric id or URL.
`collection SOURCE`	Exports the dashboards in a collection. Add `--recursive` to include nested collections.

Flags for dashboard, question and collection:

Flag	What it does
`--parameter ID=JSON`	Set a Metabase parameter, such as `period="2026-09-01"`. Repeatable.
`--allow-query-execution`	Let Metabase run saved questions when compiled SQL is needed.
`--json`	Print compact JSON.
`-o`, `--output`	Write the export to a file.

`pda migrate tableau`

pda migrate tableau configure
pda migrate tableau "Sales Overview" -o sales-overview.json

Subcommand or flag	What it does
`configure`	Asks for the Tableau server URL, site, personal access token and API version, and saves them in `pda_config.yaml`. The token is stored as plain text there, so prefer an `env()` reference.
`WORKBOOK`	The name of a workbook on the Tableau server. Exports it as JSON, with images of its worksheets.
`-o`, `--output`	Write the JSON to a file instead of the terminal.
`--dashboard`	Export one dashboard by name.
`--assets-dir`	Folder for worksheet images. Defaults to a folder next to the output.
`--project`	The Tableau project that holds the workbook.

`pda docs`

Opens this documentation in your browser after asking you to confirm.

pda docs