Deploying with push
Deploy your documentation to Blode.md with a single command.
You deploy documentation to Blode.md by running blodemd push. This page covers the command options, how directory resolution works, and what happens during a deployment.
blodemd push [dir]The optional dir argument specifies the path to your docs directory. If omitted, the CLI searches for docs.json automatically.
When you omit the dir argument, the CLI checks for docs.json in this order:
./)./docs/./apps/docs/If none of these contain a docs.json, the CLI defaults to the current directory.
If you pass an explicit directory (e.g., blodemd push my-docs), the CLI uses
that path directly without searching.
When you run blodemd push, the CLI performs these steps:
The CLI reads and parses docs.json from the resolved directory. If the
file is missing or invalid, the push fails immediately.
Authentication is resolved in this order: --api-key flag,
BLODEMD_API_KEY environment variable, stored credentials from blodemd login.
The CLI walks the docs directory recursively, skipping dotfiles (files and
directories starting with .) and node_modules. The file list is sorted
alphabetically.
A new deployment record is created on the server with the resolved branch name and commit message.
Files are base64-encoded and uploaded in batches. Each batch stays under 4 MB to work within serverless payload limits. The CLI shows progress as batches complete.
The deployment is finalized and promoted to live. Your docs are available immediately at .
If the project slug does not exist on Blode.md, the CLI offers to create it for you. This only works when you are logged in with browser OAuth (via blodemd login). API key authentication cannot auto-create projects.
When a project is created, the CLI prints an API key for use in CI/CD pipelines. Save this key -- it is only displayed once.
Project my-project created
API key for CI: bmd_abc123...
The CLI applies these rules when collecting files:
. (e.g., .git, .env) and node_modulesapplication/octet-streamThe branch name is resolved in this order:
--branch flagBLODEMD_BRANCH environment variableGITHUB_REF_NAME environment variable (auto-set by GitHub Actions)git rev-parse --abbrev-ref HEAD)mainThe commit message is resolved in this order:
--message flagBLODEMD_COMMIT_MESSAGE environment variablegit log -1 --pretty=%s)your-project.blode.md