Skip to main content

CLI

The dbdiagram CLI treats your .dbml files as the source of truth. Keep your schema in version control, push it to update your diagram, and publish docs to dbdocs.io — from your terminal or CI.

Built for AI-assisted workflows

Everything runs from a local .dbml file, so it fits IDE AI agents: let an agent edit your schema, then dbdiagram push to sync the change.

See your ERD while you edit

The CLI runs in your terminal and doesn't render diagrams. To see your ERD locally, pair it with the dbdiagram VS Code extension, which renders a live preview from your .dbml as you type.

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 your DBML to update the diagram. Pull to bring web-editor changes back into version control. This is your day-to-day loop.

Sync carries your diagram layout too, not just the schema. Table positions live in a companion .dbdiagram file next to your DBML (e.g. schema.dbdiagram), so a pulled diagram keeps its arrangement. Commit it alongside your .dbml.

Publish DB documentation​

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

dbdiagram build document

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

Automate in CI/CD​

The CLI reads a token from the DBDIAGRAM_TOKEN environment variable, so it can update your diagram or docs on every push. Generate one with dbdiagram tokens generate --name "CI token", store it as a secret, and let your 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 the full list of commands and flags (push, pull, list, delete, build, tokens, and more), see the package README on npm.