API docs go stale the moment someone edits a spec and forgets to regenerate the reference. The fix is to stop treating documentation as a manual step. If you can produce docs with a single command, you can wire that command into CI and let it run on every merge.
Doing it from the terminal has other upsides. Commands are scriptable, they leave a diff you can review, and an AI agent or a CI runner can trigger them without anyone opening a browser. No GUI clicking, no “did you remember to hit export.”
This guide walks the general open route first: turning an OpenAPI file into a standalone HTML reference or a Markdown file with a single command. Then it goes deeper on the Apidog CLI route, which pulls your docs straight out of a live project so the source of truth and the output stay in sync. If you want more background on the landscape, see our roundup of the top REST API documentation tools and the free API documentation tools worth knowing.
You need one thing to follow along: an OpenAPI 3.x file. Most of these commands accept openapi.yaml or openapi.json interchangeably.
Build an HTML reference with Redocly CLI
Redocly CLI is the quickest way to turn an OpenAPI description into a polished, self-contained HTML page. It renders your spec with Redoc and writes everything (styles, script, and content) into one file you can host anywhere or email to a teammate.
Install it globally, or skip the install and run it with npx:
npm install @redocly/cli -g
Then point it at your spec:
redocly build-docs openapi.yaml
By default this writes redoc-static.html in the current directory. Open that file in a browser and you have a full three-panel API reference. To control the filename or path, use --output:
redocly build-docs openapi.yaml --output docs/index.html
That is the whole workflow. One input file, one command, one HTML artifact. It works with Swagger 2.0 and OpenAPI 3.0/3.1 descriptions, so most existing specs render without changes. The tradeoff is scope: build-docs gives you a reference page and nothing else. Long-form guides, tutorials, and getting-started pages live outside of it.
Generate Markdown with Widdershins
Sometimes you don’t want HTML. You want Markdown you can drop into a docs site, a static-site generator, or a repo’s docs/ folder. Widdershins converts an OpenAPI, Swagger, or AsyncAPI definition into Slate-compatible Markdown.
Install it from npm:
npm install -g widdershins
Then convert your spec, sending the output to a file with -o:
widdershins openapi.yaml -o api.md
Leave off -o and Widdershins prints to stdout, which is handy if you want to pipe it somewhere. You can also toggle language tabs for code samples:
widdershins openapi.yaml --language_tabs 'shell:cURL' 'python:Python' -o api.md
Widdershins is a good fit when your docs pipeline is Markdown-first. If you’re building a broader Markdown export flow, our guide on using an API doc generator with Markdown export covers the surrounding tooling. The catch with both Redocly and Widdershins is the same: they read a static file. If your API definition lives in a design tool and drifts from the file on disk, you’re documenting yesterday’s spec.
Document from a live project with the Apidog CLI
Here’s where the integrated route pays off. Apidog isn’t open source, but its free tier plus apidog-cli gives you an alternative to stitching separate tools together: your endpoints, schemas, and written docs all live in one project, and the CLI exports from that project on demand. Nothing drifts, because the export reads the same source your team edits.
Install the CLI from npm:
npm install -g apidog-cli
If you’re setting up for the first time, our Apidog CLI installation guide covers Node versions and PATH setup. Then authenticate once with a personal access token:
apidog login --with-token <TOKEN>
The token is stored, so you don’t pass it on every call. From here, everything runs against a project ID. Add --help to any command to see its exact flags before you run it.
Import a spec into the project
If your API already lives in an OpenAPI file, bring it into a project so the CLI has something to export:
apidog import --help
apidog import --project <projectId> --format openapi --file ./openapi.json
apidog import accepts OpenAPI 3.x, Swagger 2.0, Postman, and Apidog formats, so you can pull in a Postman collection or an existing Apidog export the same way. Once the spec is imported, it becomes the live source that everything else reads from.
Export human-readable docs
This is the core command. apidog export writes OpenAPI, HTML, Markdown, or Postman, so run --help first to see the exact format and output flags your version ships, then export the project’s documentation to Markdown:
apidog export --help
apidog export --project <projectId> --format markdown --output ./api-docs.md
Open api-docs.md and you have a full reference generated from the current state of the project. Want HTML instead? Change one flag:
apidog export --project <projectId> --format html --output ./api-docs.html
You can also export back to OpenAPI when you want a portable spec to hand downstream:
apidog export --project <projectId> --format openapi --output ./openapi.json
If your project holds several services and you only want part of it documented, the export supports narrowing the scope. Check apidog export --help for the scope and ID flags in your version, since a single project can ship one doc file per service that way.
Manage the written guides, not just the reference
A reference generated from your schema is only half the story. The other half is the prose: getting-started guides, auth walkthroughs, migration notes. In Apidog those live in the project’s docs tree as Markdown documents, and the CLI manages them with the doc command group.
Start by reading the group’s help so you’re working from the exact flags your version ships:
apidog doc --help
apidog doc list --project <projectId>
From there the flow is the same shape as everything else in the CLI: run the command against your project, read the JSON result, and follow the agentHints.nextSteps it hands back. When a command wants a JSON payload, the CLI can print the schema it expects and validate your file against it before you send anything, so you catch a missing field on your machine instead of in a failed call. Check apidog cli-schema --help for the exact validate subcommand.
Publish a docs site
When the reference and guides are ready, you can manage published documentation from the terminal too. Two commands cover it, and reading their help first saves a guessed flag:
apidog docs-site --help
apidog shared-doc --help
One naming note that trips people up: a doc is a Markdown document inside the project’s API tree, docs-site manages the hosted, public documentation site, and shared-doc manages shareable documentation links. Reach for docs-site when you want a public site defined from the terminal rather than clicked together in a UI, and shared-doc when you just want a link to hand a partner. The payoff is that publishing becomes a scripted step: when your spec changes, you re-import or edit the project, then run the publish command again, and the hosted docs reflect the update.
Wire it into CI
The reason to run any of this from the CLI is repeatability. Once the commands work locally, they work in a pipeline. A minimal GitHub Actions step that regenerates and commits your Markdown reference on every push looks like this:
- name: Regenerate API docs
run: |
npm install -g apidog-cli
apidog login --with-token ${{ secrets.APIDOG_TOKEN }}
apidog export --project ${{ secrets.APIDOG_PROJECT }} --format markdown --output ./docs/api-docs.md
Swap in redocly build-docs or widdershins and the shape is identical. Docs stop being a chore someone remembers to do and become a build artifact that regenerates itself. For the full command reference, see the Apidog CLI complete guide.
Common snags
Wrong or missing project ID. Every Apidog export, doc, and docs-site call needs --project <projectId>. The ID is in the project settings, not the human-readable project name. If a command errors out complaining about the project, that’s almost always the cause.
Token not set in CI. apidog login stores the token on the machine that runs it. In a fresh CI runner there’s no stored token, so you have to run login --with-token in the same job before any export. Store the token as a secret, never in the workflow file.
Stale file exports. Redocly and Widdershins read whatever file you hand them. If your openapi.yaml is out of date, so are your docs. This is exactly the drift the Apidog route avoids by exporting from the live project instead of a file on disk.
Guessing at flags instead of reading --help. The exact flags for export, doc, docs-site, and shared-doc can vary by CLI version. Run apidog <command> --help and work from what it prints rather than a flag you half-remember. It takes two seconds and saves a failed build.
Wrapping up
Documenting an API from the terminal comes down to picking the right output. Reach for Redocly CLI when you want a standalone HTML reference, Widdershins when you want Markdown for a docs site, and the Apidog CLI when you want reference plus written guides plus a published site all exported from one live source. The last option is the one that keeps your docs honest, because the export and the thing your team edits are the same project.
Every command here is scriptable, which means every one of them belongs in CI. Set it up once and your documentation regenerates itself on every change. Download Apidog to get the CLI and try the export flow against your own project, or read more about how Apidog fits into an API-first workflow.
