DoltHub CLI command reference#

Reference for dh dev.

Development reference; this bundle is not stamped for publication.

Use dh --help, dh <command> --help, or dh help <command> to explore commands in the terminal.

dh#

Work with DoltHub from the command line.

Usage#

dh [command] [flags]

Flags#

Related commands#

• dh api
• dh auth
• dh branch
• dh browse
• dh completion
• dh config
• dh db
• dh job
• dh pr
• dh release
• dh sql
• dh table
• dh tag
• dh version

All commands#

dh api#

Make an authenticated DoltHub API request

Usage#

dh api ENDPOINT [flags]

Arguments#

Flags#

Constraints#

• Defaults to GET, or POST when the request body is nonempty; —method overrides this.
• —raw-field builds string JSON values; —field recognizes booleans, null, and signed integers; other values stay strings. —input reads the request body from a file (or - for stdin); additional fields then become query parameters.
• —paginate follows next-page tokens. —slurp requires —paginate and wraps complete page responses in an array. —jq and —template are mutually exclusive.

Output#

Prints the raw API response body by default. —include also prints HTTP status and headers; —silent suppresses the body. —jq or —template formats the response directly, without —json.

Examples#

dh api user
dh api databases/OWNER/DATABASE --jq .

Related commands#

• dh

dh auth#

Authenticate dh with DoltHub

Usage#

dh auth [command] [flags]

Flags#

Related commands#

• dh
• dh auth login
• dh auth logout
• dh auth status

dh auth login#

Log in to DoltHub in a web browser

Usage#

dh auth login [flags]

Flags#

Constraints#

• Unset DH_TOKEN before browser login. The default production host includes a public OAuth client ID; custom hosts require DH_OAUTH_CLIENT_ID. —hostname overrides DH_HOST and saved host configuration for login.

Output#

Opens browser authentication using OAuth PKCE, saves credentials, and prints the signed-in identity. Access tokens refresh automatically during authenticated requests. The system keyring is preferred; an unavailable keyring falls back to a user credential file with a notice.

Examples#

dh auth login
dh auth login --hostname www.dolthub.com

Related commands#

• dh auth

dh auth logout#

Log out of DoltHub

Usage#

dh auth logout [flags]

Flags#

Constraints#

• If DH_TOKEN is set, unset the environment variable instead. Logout does not clear that variable.

Output#

Removes the saved active identity and its local credential for the selected host, then prints confirmation. Interactive use asks for confirmation unless —yes is set.

Examples#

dh auth logout --yes

Related commands#

• dh auth

dh auth status#

View authentication status

Usage#

dh auth status [flags]

Flags#

Output#

Checks the configured host and reports the active identity and credential source without printing the token. Returns an authentication error when credentials are missing or invalid.

Examples#

dh auth status

Related commands#

• dh auth

dh branch#

Work with database branches

Usage#

dh branch [command] [flags]

Flags#

Related commands#

• dh
• dh branch create

dh branch create#

Create a database branch

Select a database with —db, then DH_DB, saved database configuration, or local Dolt remotes (in that order). Use dh config set db OWNER/DB to save a default. Multiple remotes prompt interactively; scripts must select a database explicitly when discovery is ambiguous.

Use —json with a comma-separated list of fields for structured output. —jq and —template transform the selected JSON and require —json.

Usage#

dh branch create NAME [flags]

Arguments#

Flags#

Constraints#

• Exactly one of —from-branch or —from-commit is required.

JSON fields#

head_commit_sha, last_updated_at, name

Output#

Prints the created branch and commit, or selected JSON fields.

Examples#

dh branch create feature/people --db OWNER/people --from-branch main

Related commands#

• dh branch

dh browse#

Open a database repository in the browser

Select a database with —db, then DH_DB, saved database configuration, or local Dolt remotes (in that order). Use dh config set db OWNER/DB to save a default. Multiple remotes prompt interactively; scripts must select a database explicitly when discovery is ambiguous.

Usage#

dh browse [NUMBER] [flags]

Arguments#

Flags#

Constraints#

• Positional NUMBER, —pull, and —branch are mutually exclusive selectors.

Output#

Opens the selected database, branch, or pull request in a browser.

Examples#

dh browse --db OWNER/people
dh browse 1 --db OWNER/people

Related commands#

• dh

dh completion#

Generate shell completion scripts

Usage#

dh completion {bash|fish|powershell|zsh} [flags]

Arguments#

Flags#

Output#

Writes a shell completion script to stdout. Save or source it using your shell’s completion setup; this command does not install the script.

Examples#

dh completion bash > dh.bash
dh completion zsh > _dh

Related commands#

• dh

dh config#

Manage dh configuration

Usage#

dh config [command] [flags]

Flags#

Related commands#

• dh
• dh config get
• dh config list
• dh config set

dh config get#

Get a configuration value

Usage#

dh config get KEY [flags]

Arguments#

Flags#

Output#

Prints the effective configuration value, including DH_HOST or DH_DB overrides. An unset database produces no output and exits successfully.

Examples#

dh config get db

Related commands#

• dh config

dh config list#

List configuration values

Usage#

dh config list [flags]

Flags#

Output#

Prints KEY, VALUE, and SOURCE for host and db, showing DH_HOST/DH_DB, saved configuration, or default/unset values. It does not discover local remotes.

Examples#

dh config list

Related commands#

• dh config

dh config set#

Set a configuration value

Usage#

dh config set KEY VALUE [flags]

Arguments#

Flags#

Constraints#

• Values must not be empty. Config is saved under the platform user config directory in dh/config.json.

Output#

Saves the configuration without printing a success message. DH_HOST and DH_DB overrides still take precedence.

Examples#

dh config set db OWNER/DATABASE
dh config set host www.dolthub.com

Related commands#

• dh config

dh db#

Work with DoltHub database repositories

Usage#

dh db [command] [flags]

Flags#

Related commands#

• dh
• dh db create
• dh db fork
• dh db view

dh db create#

Create a database repository

Use —json with a comma-separated list of fields for structured output. —jq and —template transform the selected JSON and require —json.

Usage#

dh db create [OWNER/]NAME [flags]

Arguments#

Flags#

Constraints#

• —public and —private are mutually exclusive. Noninteractive use requires a name and one visibility flag. Interactive use prompts for missing name, visibility, and optionally description.

JSON fields#

description, fork_network_count, last_write_at, name, network_root, owner, parent, size_bytes, star_count, visibility

Output#

Prints the created database identifier and browser URL, or the selected database fields with —json.

Examples#

dh db create OWNER/people --private

Related commands#

• dh db

dh db fork#

Fork a database repository

Select a database with —db, then DH_DB, saved database configuration, or local Dolt remotes (in that order). Use dh config set db OWNER/DB to save a default. Multiple remotes prompt interactively; scripts must select a database explicitly when discovery is ambiguous.

Use —json with a comma-separated list of fields for structured output. —jq and —template transform the selected JSON and require —json.

Usage#

dh db fork [DATABASE] [flags]

Arguments#

Flags#

Constraints#

• A positional DATABASE and —db cannot be combined. —org selects the owner of the new fork; when omitted, the authenticated user owns it.

JSON fields#

cancelable, created_at, error, href, id, result, status, type

Output#

Waits for completion and prints job details by default. Progress goes to stderr. —json selects job fields. With —no-wait, prints the accepted ID and HREF instead; use —json id,href for structured acceptance. Acceptance is not completion. A failed job returns a nonzero exit status. Interrupting the local wait does not cancel the remote job.

Examples#

dh db fork OWNER/people --org MY_USER

Related commands#

• dh db

dh db view#

View a database repository

Select a database with —db, then DH_DB, saved database configuration, or local Dolt remotes (in that order). Use dh config set db OWNER/DB to save a default. Multiple remotes prompt interactively; scripts must select a database explicitly when discovery is ambiguous.

Use —json with a comma-separated list of fields for structured output. —jq and —template transform the selected JSON and require —json.

Usage#

dh db view [DATABASE] [flags]

Arguments#

Flags#

Constraints#

• A positional DATABASE and —db cannot be combined. —web cannot be combined with structured output. —forks requests immediate forks; it does not recursively traverse the fork network.

JSON fields#

description, fork_network_count, forks, last_write_at, name, network_root, owner, parent, size_bytes, star_count, visibility

Output#

Prints database details, optionally including immediate forks. —json selects fields; —web opens the browser instead.

Examples#

dh db view OWNER/people
dh db view OWNER/people --json name,visibility

Related commands#

• dh db

dh job#

Work with asynchronous jobs

Usage#

dh job [command] [flags]

Flags#

Related commands#

• dh
• dh job list
• dh job view
• dh job watch

dh job list#

List database jobs

Select a database with —db, then DH_DB, saved database configuration, or local Dolt remotes (in that order). Use dh config set db OWNER/DB to save a default. Multiple remotes prompt interactively; scripts must select a database explicitly when discovery is ambiguous.

Use —json with a comma-separated list of fields for structured output. —jq and —template transform the selected JSON and require —json.

Usage#

dh job list [flags]

Flags#

Constraints#

• —limit must be positive.

JSON fields#

cancelable, created_at, error, id, result, status, type

Output#

Prints jobs for the selected database, or a JSON array of selected fields, fetching pages up to —limit.

Examples#

dh job list --db OWNER/people

Related commands#

• dh job

dh job view#

View an asynchronous job

Use —json with a comma-separated list of fields for structured output. —jq and —template transform the selected JSON and require —json.

Usage#

dh job view ID [flags]

Arguments#

Flags#

Constraints#

• Authentication is required. Uses DH_HOST or saved/default host configuration, not a database selector.

JSON fields#

cancelable, created_at, error, id, result, status, type

Output#

Prints current job details or selected JSON fields. This is a snapshot; use dh job watch to wait for completion.

Examples#

dh job view JOB_ID

Related commands#

• dh job

dh job watch#

Watch an asynchronous job

Use —json with a comma-separated list of fields for structured output. —jq and —template transform the selected JSON and require —json.

Usage#

dh job watch ID [flags]

Arguments#

Flags#

Constraints#

• Authentication is required. —interval must be positive; it sets the initial polling interval. Uses the configured host.

JSON fields#

cancelable, created_at, error, id, result, status, type

Output#

Polls until the job finishes and prints its details or selected JSON fields. Progress goes to stderr; failed or canceled jobs return a nonzero exit status. Stopping the local wait does not cancel remote work.

Examples#

dh job watch JOB_ID --json id,status,result

Related commands#

• dh job

dh pr#

Work with pull requests

Usage#

dh pr [command] [flags]

Flags#

Related commands#

• dh
• dh pr close
• dh pr comment
• dh pr create
• dh pr edit
• dh pr list
• dh pr merge
• dh pr reopen
• dh pr view

dh pr close#

Close a pull request

Select a database with —db, then DH_DB, saved database configuration, or local Dolt remotes (in that order). Use dh config set db OWNER/DB to save a default. Multiple remotes prompt interactively; scripts must select a database explicitly when discovery is ambiguous.

Use —json with a comma-separated list of fields for structured output. —jq and —template transform the selected JSON and require —json.

Usage#

dh pr close NUMBER [flags]

Arguments#

Flags#

JSON fields#

created_at, creator, description, from_branch, pull_number, state, title, to_branch

Output#

Prints the updated pull request, or selected JSON fields.

Examples#

dh pr close 1 --db OWNER/people

Related commands#

• dh pr

dh pr comment#

Add a pull request comment

Select a database with —db, then DH_DB, saved database configuration, or local Dolt remotes (in that order). Use dh config set db OWNER/DB to save a default. Multiple remotes prompt interactively; scripts must select a database explicitly when discovery is ambiguous.

Use —json with a comma-separated list of fields for structured output. —jq and —template transform the selected JSON and require —json.

Usage#

dh pr comment NUMBER [flags]

Arguments#

Flags#

Constraints#

• Comment body must not be empty. Noninteractive use requires —body or —body-file; interactive use can prompt. The flags are mutually exclusive. —body-file - reads stdin.

JSON fields#

author, body, comment_id, created_at, updated_at

Output#

Prints the comment author, creation time, and body, or selected JSON fields.

Examples#

dh pr comment 1 --db OWNER/people --body "Ready for review"

Related commands#

• dh pr

dh pr create#

Create a pull request

Select a database with —db, then DH_DB, saved database configuration, or local Dolt remotes (in that order). Use dh config set db OWNER/DB to save a default. Multiple remotes prompt interactively; scripts must select a database explicitly when discovery is ambiguous.

Use —json with a comma-separated list of fields for structured output. —jq and —template transform the selected JSON and require —json.

Usage#

dh pr create [flags]

Flags#

Constraints#

• Noninteractive use requires —title, —head, and —base; interactive use prompts for missing values.
• —head accepts BRANCH or OWNER/DB:BRANCH for a cross-database source. —base is a branch in the selected target database.
• —body and —body-file are mutually exclusive; —body-file - reads stdin.

JSON fields#

created_at, creator, description, from_branch, pull_number, state, title, to_branch

Output#

Prints the created pull request number, title, state, and source/target branches, or selected JSON fields.

Examples#

dh pr create --db OWNER/people --head feature/people --base main --title "Update people"

Related commands#

• dh pr

dh pr edit#

Edit a pull request

Select a database with —db, then DH_DB, saved database configuration, or local Dolt remotes (in that order). Use dh config set db OWNER/DB to save a default. Multiple remotes prompt interactively; scripts must select a database explicitly when discovery is ambiguous.

Use —json with a comma-separated list of fields for structured output. —jq and —template transform the selected JSON and require —json.

Usage#

dh pr edit NUMBER [flags]

Arguments#

Flags#

Constraints#

• At least one of —title, —body, or —body-file is required. —body and —body-file are mutually exclusive; —body-file - reads stdin.

JSON fields#

created_at, creator, description, from_branch, pull_number, state, title, to_branch

Output#

Prints the updated pull request, or selected JSON fields.

Examples#

dh pr edit 1 --db OWNER/people --title "Update people data"

Related commands#

• dh pr

dh pr list#

List pull requests

Select a database with —db, then DH_DB, saved database configuration, or local Dolt remotes (in that order). Use dh config set db OWNER/DB to save a default. Multiple remotes prompt interactively; scripts must select a database explicitly when discovery is ambiguous.

Use —json with a comma-separated list of fields for structured output. —jq and —template transform the selected JSON and require —json.

Usage#

dh pr list [flags]

Flags#

Constraints#

• —state must be open, closed, merged, or all. —limit must be positive.

JSON fields#

created_at, creator, description, pull_number, state, title

Output#

Prints pull request rows, or a JSON array of selected fields. Fetches additional API pages up to —limit.

Examples#

dh pr list --db OWNER/people --state open

Related commands#

• dh pr

dh pr merge#

Merge a pull request

Select a database with —db, then DH_DB, saved database configuration, or local Dolt remotes (in that order). Use dh config set db OWNER/DB to save a default. Multiple remotes prompt interactively; scripts must select a database explicitly when discovery is ambiguous.

Use —json with a comma-separated list of fields for structured output. —jq and —template transform the selected JSON and require —json.

Usage#

dh pr merge NUMBER [flags]

Arguments#

Flags#

JSON fields#

cancelable, created_at, error, href, id, result, status, type

Output#

Waits for completion and prints job details by default. Progress goes to stderr. —json selects job fields. With —no-wait, prints the accepted ID and HREF instead; use —json id,href for structured acceptance. Acceptance is not completion. A failed job returns a nonzero exit status. Interrupting the local wait does not cancel the remote job.

Examples#

dh pr merge 1 --db OWNER/people

Related commands#

• dh pr

dh pr reopen#

Reopen a pull request

Select a database with —db, then DH_DB, saved database configuration, or local Dolt remotes (in that order). Use dh config set db OWNER/DB to save a default. Multiple remotes prompt interactively; scripts must select a database explicitly when discovery is ambiguous.

Use —json with a comma-separated list of fields for structured output. —jq and —template transform the selected JSON and require —json.

Usage#

dh pr reopen NUMBER [flags]

Arguments#

Flags#

JSON fields#

created_at, creator, description, from_branch, pull_number, state, title, to_branch

Output#

Prints the updated pull request, or selected JSON fields.

Examples#

dh pr reopen 1 --db OWNER/people

Related commands#

• dh pr

dh pr view#

View a pull request

Select a database with —db, then DH_DB, saved database configuration, or local Dolt remotes (in that order). Use dh config set db OWNER/DB to save a default. Multiple remotes prompt interactively; scripts must select a database explicitly when discovery is ambiguous.

Use —json with a comma-separated list of fields for structured output. —jq and —template transform the selected JSON and require —json.

Usage#

dh pr view NUMBER [flags]

Arguments#

Flags#

Constraints#

• —web cannot be combined with structured output.

JSON fields#

comments, created_at, creator, description, from_branch, pull_number, state, title, to_branch

Output#

Prints pull request details, optionally including comments; —json selects fields and —web opens the browser.

Examples#

dh pr view 1 --db OWNER/people --comments

Related commands#

• dh pr

dh release#

Work with database releases

Usage#

dh release [command] [flags]

Flags#

Related commands#

• dh
• dh release create
• dh release list
• dh release view

dh release create#

Create a database release

Select a database with —db, then DH_DB, saved database configuration, or local Dolt remotes (in that order). Use dh config set db OWNER/DB to save a default. Multiple remotes prompt interactively; scripts must select a database explicitly when discovery is ambiguous.

Use —json with a comma-separated list of fields for structured output. —jq and —template transform the selected JSON and require —json.

Usage#

dh release create TAG [flags]

Arguments#

Flags#

Constraints#

• —title and —target are required. —target is an exact commit SHA. Use —create-tag if the tag does not yet exist.
• —notes and —notes-file are mutually exclusive; —notes-file - reads stdin.

JSON fields#

commit_sha, created_at, description, tag, title, updated_at

Output#

Prints the release tag, title, and commit, or selected JSON fields.

Examples#

dh release create v1 --db OWNER/people --title "First dataset" --target COMMIT_SHA --create-tag

Related commands#

• dh release

dh release list#

List database releases

Select a database with —db, then DH_DB, saved database configuration, or local Dolt remotes (in that order). Use dh config set db OWNER/DB to save a default. Multiple remotes prompt interactively; scripts must select a database explicitly when discovery is ambiguous.

Use —json with a comma-separated list of fields for structured output. —jq and —template transform the selected JSON and require —json.

Usage#

dh release list [flags]

Flags#

Constraints#

• —limit must be positive.

JSON fields#

commit_sha, created_at, description, tag, title, updated_at

Output#

Prints releases, or a JSON array of selected fields. Fetches additional API pages up to —limit.

Examples#

dh release list --db OWNER/people

Related commands#

• dh release

dh release view#

View a database release

Select a database with —db, then DH_DB, saved database configuration, or local Dolt remotes (in that order). Use dh config set db OWNER/DB to save a default. Multiple remotes prompt interactively; scripts must select a database explicitly when discovery is ambiguous.

Use —json with a comma-separated list of fields for structured output. —jq and —template transform the selected JSON and require —json.

Usage#

dh release view TAG [flags]

Arguments#

Flags#

Constraints#

• —web cannot be combined with structured output.

JSON fields#

commit_sha, created_at, description, tag, title, updated_at

Output#

Prints release details or selected JSON fields. —web opens the release in the browser.

Examples#

dh release view v1 --db OWNER/people

Related commands#

• dh release

dh sql#

Run SQL against a database

Select a database with —db, then DH_DB, saved database configuration, or local Dolt remotes (in that order). Use dh config set db OWNER/DB to save a default. Multiple remotes prompt interactively; scripts must select a database explicitly when discovery is ambiguous.

Use —json with a comma-separated list of fields for structured output. —jq and —template transform the selected JSON and require —json.

Usage#

dh sql [QUERY] [flags]

Arguments#

Flags#

Constraints#

• Provide only one SQL source: argument, —file, or stdin. —file - reads stdin. Empty queries are rejected.
• —jq and —template require —json. JSON fields must be valid for the selected read/write mode.

Read queries#

Requires —branch with a branch, or —ref with a branch, tag, or commit. —branch and —ref are mutually exclusive. —limit must be positive when supplied; —timeout must be between 1ms and 60s in whole milliseconds. —from-branch and —no-wait require write mode.

JSON fields: columns, message, rows, status, warnings.

Write queries#

Requires —write and —branch. —from-branch defaults to —branch and supplies the source branch. —ref, —limit, and —timeout are read-only flags. Acceptance does not imply successful completion; watch the returned job ID.

JSON fields: cancelable, created_at, error, href, id, result, status, type.

JSON fields#

cancelable, columns, created_at, error, href, id, message, result, rows, status, type, warnings

Output#

Reads print rows to stdout and warnings to stderr, or selected JSON fields. Unsuccessful query status returns a nonzero exit code. Writes wait for a job and print its details; —no-wait prints ID/HREF after acceptance. For acceptance JSON use —json id,href.

Examples#

dh sql --db OWNER/people --branch main "select * from people limit 10"
dh sql --write --db OWNER/people --branch feature/people --from-branch main --file update.sql

Related commands#

• dh

dh table#

Work with DoltHub tables

Usage#

dh table [command] [flags]

Flags#

Related commands#

• dh
• dh table import

dh table import#

Upload a CSV, PSV, XLSX, or JSON file and import it into a table. Creates a table by default. JSON requires —update or —replace. Files must be regular, nonempty files of at most 1 GiB. Upload URLs expire after 10 minutes; failed uploads must be restarted. Keep the file unchanged until uploading finishes. —no-wait still waits for the file upload.

Select a database with —db, then DH_DB, saved database configuration, or local Dolt remotes (in that order). Use dh config set db OWNER/DB to save a default. Multiple remotes prompt interactively; scripts must select a database explicitly when discovery is ambiguous.

Use —json with a comma-separated list of fields for structured output. —jq and —template transform the selected JSON and require —json.

Usage#

dh table import <table> <file> [flags]

Arguments#

Flags#

Constraints#

• —branch is required. Default mode creates a table. —overwrite, —update, and —replace target an existing table and are mutually exclusive. JSON requires —update or —replace.
• File format comes from the extension unless —file-type is given. Primary keys may be comma-separated or repeated; empty primary-key names are rejected.
• Keep the file unchanged during upload. Storage URLs expire after ten minutes; failed uploads must restart, with no resume or URL refresh. Ctrl+C does not abort the storage session or cancel a submitted import.

JSON fields#

cancelable, created_at, error, href, id, result, status, type

Output#

Waits for completion and prints job details by default. Progress goes to stderr. —json selects job fields. With —no-wait, prints the accepted ID and HREF instead; use —json id,href for structured acceptance. Acceptance is not completion. A failed job returns a nonzero exit status. Interrupting the local wait does not cancel the remote job. —no-wait still waits for the entire upload. On an ambiguous submission error, check dh job list before retrying.

Examples#

dh table import people people.csv --db OWNER/people --branch main --primary-key id
dh table import people changes.json --db OWNER/people --branch main --update

Related commands#

• dh table

dh tag#

Work with database tags

Usage#

dh tag [command] [flags]

Flags#

Related commands#

• dh
• dh tag create

dh tag create#

Create a database tag

Select a database with —db, then DH_DB, saved database configuration, or local Dolt remotes (in that order). Use dh config set db OWNER/DB to save a default. Multiple remotes prompt interactively; scripts must select a database explicitly when discovery is ambiguous.

Use —json with a comma-separated list of fields for structured output. —jq and —template transform the selected JSON and require —json.

Usage#

dh tag create NAME [flags]

Arguments#

Flags#

Constraints#

• Exactly one of —from-branch or —from-commit is required. —message supplies an annotation.

JSON fields#

commit_sha, message, name, tagged_at

Output#

Prints the created tag and commit, or selected JSON fields.

Examples#

dh tag create v1 --db OWNER/people --from-branch main --message "First dataset"

Related commands#

• dh tag

dh version#

Show dh version information

Usage#

dh version [flags]

Flags#

Output#

Prints dh version followed by the build version. —short prints only the version.

Examples#

dh version
dh version --short

Related commands#

• dh