dbdiagram-cli

A CLI tool for dbdiagram.io.

Install

npm install -g dbdiagram
# or
yarn global add dbdiagram
# or
pnpm add -g dbdiagram

Usage

Authentication

Manage login state for dbdiagram/dbdocs.

Options:

• --json — Output status as JSON (auth status only)

dbdiagram auth login            # log in via browser
dbdiagram auth logout           # clear stored credentials
dbdiagram auth status           # show who you're logged in as

Tip: Set DBDIAGRAM_TOKEN=<token> to authenticate without a browser (see Tokens).

Init

Creates or updates .dbdiagram/settings.json so you don't need to repeat flags on every command.

Options:

• --entry <filepath> — Path to your DBML entry file
• --diagram-id <id> — Diagram ID (from dbdiagram.io/d/<id>)
• --workspace <id> — Workspace ID (omit for personal workspace)
• --document-source <mode> — DBML source for build document: file or diagram
• --workspace-url <name> — dbdocs workspace URL name (from dbdocs.io/<name>)
• --project-url <name> — dbdocs project URL name (from dbdocs.io/<workspace>/<name>)

# set up a diagram project
dbdiagram init --entry schema.dbml --diagram-id <id>

# set up a dbdocs project
dbdiagram init --entry schema.dbml --workspace-url myteam --project-url myteam/myproject

Push

Push a local DBML file to create or update a diagram on dbdiagram.io.

Options:

• --name <name> — Name for the diagram
• --diagram-id <id> — Update an existing diagram (omit to create new)
• --workspace <id> — Create in a specific workspace (ignored when --diagram-id is set)
• --new — Force-create a new diagram, ignoring diagram-id from settings
• --json — Output result as JSON

dbdiagram push schema.dbml --name "My Diagram"         # create new diagram
dbdiagram push schema.dbml --diagram-id <id>           # update existing diagram
dbdiagram push schema.dbml --workspace <id>            # create in a workspace
dbdiagram push schema.dbml --new                       # force-create, ignoring settings

Pull

Pull DBML content from a diagram on dbdiagram.io.

Options:

• --diagram-id <id> — The diagram to pull from
• -o, --out-file <filepath> — Save to a file (omit to use the configured entry file from settings, or print to stdout)

dbdiagram pull --diagram-id <id>                       # print to stdout (or save to the configured entry file)
dbdiagram pull --diagram-id <id> -o schema.dbml        # save to a specific file

List

List diagrams or documents.

Options:

• --workspace <id> — Filter by workspace (omit for personal workspace)
• --json — Output as JSON

dbdiagram list                                         # list your diagrams
dbdiagram list --workspace <id>                        # list diagrams in a workspace
dbdiagram list document                                # list your dbdocs documents
dbdiagram list document --workspace <name>             # list documents in a workspace

Delete

Delete a diagram.

Options:

• --diagram-id <id> — The diagram to delete
• -f, --force — Skip confirmation prompt
• --json — Output result as JSON

dbdiagram delete --diagram-id <id>                     # delete with confirmation
dbdiagram delete --diagram-id <id> --force             # delete without confirmation

Build

Publish a dbdocs document from a local DBML file or a cloud diagram.

Options:

• --from-file <filepath> — Use a local DBML file as source (required if not using --from-diagram)
• --from-diagram <id> — Use a cloud diagram as source (required if not using --from-file)
• --project <name> — Target project as <workspace>/<project> or just <project>
• --version-name <name> — Version label for this publish
• --json — Output result as JSON

dbdiagram build document --from-file schema.dbml                               # publish from local file
dbdiagram build document --from-diagram <id>                                   # publish from cloud diagram
dbdiagram build document --from-file schema.dbml --project myteam/myproject    # publish to a specific project
dbdiagram build document --from-file schema.dbml --version-name "v1.2.0"       # publish with a version label

Tokens

Manage CLI tokens for non-interactive authentication.

Options:

• --name <name> — Name for the token (generate only)
• -f, --force — Skip confirmation (delete only)
• --json — Output as JSON

dbdiagram tokens generate --name "CI token"            # create a named token
dbdiagram tokens list                                  # list all tokens
dbdiagram tokens delete <token_id>                     # delete a token (with confirmation)
dbdiagram tokens delete <token_id> --force             # delete without confirmation

Set the generated token as DBDIAGRAM_TOKEN=<value> in your environment to authenticate without browser login.

Development

yarn install
yarn dev        # run with tsx (no build needed)

yarn build      # compile to dist/
yarn start      # run compiled output

Test

yarn test       # run tests for changed files with coverage
yarn test:all   # run all tests