Integrations

CLI

Run a sync against your working tree before anything is pushed. Useful in a pre-push hook, in CI, and for trying Docsmith on a repository you are not ready to connect.

Install

npm install --global @docsmith/cli
# or
brew install docsmith/tap/docsmith
# or, no install
npx @docsmith/cli sync --help

Node 20 or later. The Homebrew formula ships a single static binary with no runtime dependency.

Authenticate

docsmith login
# opens a browser, stores a token in ~/.config/docsmith/credentials

# or, non-interactively — the right choice in CI
export DOCSMITH_API_KEY=dsk_live_7Kx2mQ...

The environment variable wins over the stored credential when both are present.

docsmith sync

The command you will actually use.

# everything since you branched off main
docsmith sync --base main --docs docs/

# a specific range
docsmith sync --diff HEAD~3..HEAD --docs docs/

# uncommitted work, before you commit it
docsmith sync --working-tree --docs docs/

# one page against one change
docsmith sync --diff HEAD~1..HEAD --page docs/guides/retries.md

Flag	Default	Notes
`--base <ref>`	`main`	Diff the current HEAD against this ref.
`--diff <range>`	—	Any git range. Overrides `--base`.
`--working-tree`	off	Use uncommitted changes, staged and unstaged.
`--docs <glob>`	from `.docsmith.yml`	Where the documentation is.
`--page <path>`	—	Check exactly one page and skip reach analysis.
`--format`	`pretty`	`pretty`, `json` or `sarif`.
`--write`	off	Apply accepted drafts to disk. Prompts per page unless `--yes`.
`--fail-on`	`none`	`none`, `any` or `breaking`. Controls the exit code.

Output

$ docsmith sync --base main --docs docs/

  Reading change ......... 2 files, +14 −9
  Reach .................. 3 pages
  Detect ................. 2 findings across 1 page
  Draft .................. 1 page rewritten

  docs/guides/retries.md                              STALE

    Defaults · breaking · 94%
    > By default the client makes up to 5 attempts and waits a
    > fixed 200 ms between them.
    DEFAULT_ATTEMPTS moved from 5 to 3; delayMs replaced by
    baseDelayMs (250, exponential).

    docs/guides/retries.md  +3 −3     run with --write to apply

  docs/webhooks/verifying.md                        CURRENT
  docs/index.md                                     CURRENT

  3 syncs used · 27 remaining this month · 6.4s

In a pre-push hook

# .git/hooks/pre-push
#!/bin/sh
docsmith sync --base origin/main --docs docs/ --fail-on breaking || {
  echo
  echo "Documentation is stale. Fix it, or push with --no-verify."
  exit 1
}

Start with --fail-on none so the hook only reports. Turn it up once the team has seen a fortnight of output and trusts it — a hook that blocks a push on its first day gets deleted on its second.

In CI

- name: Check documentation
  env:
    DOCSMITH_API_KEY: ${{ secrets.DOCSMITH_API_KEY }}
  run: |
    npx @docsmith/cli sync \
      --base ${{ github.event.pull_request.base.sha }} \
      --docs docs/ \
      --format sarif > docsmith.sarif

- uses: github/codeql-action/upload-sarif@v3
  with: { sarif_file: docsmith.sarif }

SARIF output puts findings inline on the pull request diff, at the exact line of the affected passage, using GitHub’s own annotation UI. A ready-made action is on the GitHub app page if you would rather not write the step yourself.

Other commands

Command	Does
`docsmith index --docs docs/`	Show what Docsmith extracted from each page: symbols, literals, flags. The fastest way to understand why a page was or was not reached.
`docsmith drafts list`	Pending drafts across your connected repositories.
`docsmith drafts approve <id>`	Approve from the terminal. Add `--edit` to open the draft in `$EDITOR` first.
`docsmith webhooks listen`	Tunnel deliveries to a local endpoint for development.
`docsmith usage`	Syncs used this month, and when the counter resets.
`docsmith doctor`	Check credentials, config, git state and connectivity. Run this first when something is wrong.

Exit codes

Code	Meaning
`0`	Completed. With `--fail-on none` this is returned even when pages are stale.
`1`	Findings met the `--fail-on` threshold.
`2`	Bad usage — unknown flag, missing argument, no git repo.
`3`	Authentication failed.
`4`	Quota exhausted for the month.
`5`	Service error. The sync was not counted; retrying is safe.

What the CLI sends

The diff of the range you asked for, and the text of the candidate pages. Not your git history, not your remotes, not files the change did not touch, and no telemetry about your machine. Run docsmith sync --dry-run --format json to see the exact payload before it goes anywhere.

Questions: support@docsmithhq.com.