Skip to main content

CLI

The dbdiagram CLI treats your .dbml files as the source of truth. Keep your schema in version control, then use the CLI to sync it with a diagram and publish documentation to dbdocs.io — all from the same file. This keeps your diagram and docs in lockstep with your codebase and lets you automate updates from CI/CD.

Built for AI-assisted workflows

Because everything is driven from a local .dbml file, the CLI works naturally with IDE AI agents. Let an agent edit your schema file, then run dbdiagram push to reflect the change — no manual copy-pasting into the web editor.

See your ERD while you edit

The CLI runs in your terminal and doesn't render diagrams. To visualize your schema locally, pair it with the dbdiagram VS Code extension — it renders a live ERD from your .dbml file right in your editor as you type, no cloud round-trip needed. Edit and preview locally with the extension, then use the CLI to sync and publish.

Installation​

npm install -g dbdiagram

Requires Node.js >= 22.14. Then log in:

dbdiagram auth login

The core workflow​

The CLI supports two jobs, and both start from the same DBML file:

  1. Sync the diagram — while you're actively designing, keep a diagram in sync with the .dbml file in your repo.
  2. Build documentation — when the schema is ready, publish it as a browsable document on dbdocs.io.

Run dbdiagram init once per project to connect these pieces — it links your DBML file to a diagram and, optionally, a dbdocs project:

dbdiagram init \
  --entry schema.dbml \
  --diagram-id <id> \
  --workspace-url myteam \
  --project-url myteam/myproject
  • --entry — your DBML file.
  • --diagram-id — the diagram to sync, from its URL dbdiagram.io/d/<id>.
  • --workspace-url / --project-url — the dbdocs workspace and project to publish to, from dbdocs.io/<workspace>/<project>. Omit these if you only need diagram sync.

After this, every other command knows its target, so you can run them without repeating any flags. Commit the generated .dbdiagram/settings.json so your teammates and CI share the same setup.

Sync diagram​

push and pull keep your DBML file and your diagram pointing at the same schema:

dbdiagram push    # send local DBML → update the diagram
dbdiagram pull    # fetch the diagram → update local DBML

Push after editing DBML in your repo — with a text editor or an AI agent — to update the diagram. Pull to bring changes made in the web editor back into version control. This is the loop you'll run day-to-day.

Publish DB documentation​

build document publishes your schema as a dbdocs.io document — a browsable, shareable reference for your database, separate from the interactive diagram:

dbdiagram build document

Re-run it whenever the schema changes to publish a fresh version.

Automate in CI/CD​

Because the CLI accepts a token via the DBDIAGRAM_TOKEN environment variable, you can keep your diagram or docs up to date automatically on every push. Generate a token once with dbdiagram tokens generate --name "CI token", store it as a secret, and let the committed project setup point the CLI at the right diagram:

# .github/workflows/sync-diagram.yml
name: Sync dbdiagram
on:
  push:
    branches: [main]
    paths: ['schema.dbml']
jobs:
  sync:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: 22
      - run: npm install -g dbdiagram
      - run: dbdiagram push
        env:
          DBDIAGRAM_TOKEN: ${{ secrets.DBDIAGRAM_TOKEN }}

Swap the last step for dbdiagram build document if you want CI to publish dbdocs instead of (or in addition to) updating the diagram.

Full command reference​

This page covers the common workflows. For every command, flag, and option — push, pull, list, delete, build, tokens, and more — see the package README on npm.