> ## Documentation Index
> Fetch the complete documentation index at: https://docs.blode.md/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

## Command

```bash
blodemd push [dir]
```

The optional `dir` argument specifies the path to your docs directory. If omitted, the CLI searches for `docs.json` automatically.

## Options

- `--project <slug>` (type: string): Project slug. Overrides docs.json `slug`. Can also be set with `BLODEMD_PROJECT`. If `slug` is missing, the CLI temporarily falls back to docs.json `name` for backward compatibility.
- `--api-key <token>` (type: string): API key for authentication. Overrides stored credentials. Can also be set with `BLODEMD_API_KEY`.
- `--api-url <url>` (type: string, default: https://api.blode.md): API base URL. Can also be set with `BLODEMD_API_URL`.
- `--branch <name>` (type: string): Git branch name attached to the deployment. Can also be set with `BLODEMD_BRANCH`.
- `--message <msg>` (type: string): Deploy message. Can also be set with `BLODEMD_COMMIT_MESSAGE`.

## Directory resolution

When you omit the `dir` argument, the CLI checks for `docs.json` in this order:

1. Current working directory (`./`)
2. `./docs/`
3. `./apps/docs/`

If none of these contain a `docs.json`, the CLI defaults to the current directory.

> [!INFO]
> If you pass an explicit directory (e.g., `blodemd push my-docs`), the CLI uses
>   that path directly without searching.

## What happens during a push

When you run `blodemd push`, the CLI performs these steps:

  1. **Validate configuration**

The CLI reads and parses `docs.json` from the resolved directory. If the
    file is missing or invalid, the push fails immediately.
  1. **Resolve credentials**

Authentication is resolved in this order: `--api-key` flag,
    `BLODEMD_API_KEY` environment variable, stored credentials from `blodemd
    login`.
  1. **Collect files**

The CLI walks the docs directory recursively, skipping dotfiles (files and
    directories starting with `.`) and `node_modules`. The file list is sorted
    alphabetically.
  1. **Create deployment**

A new deployment record is created on the server with the resolved branch
    name and commit message.
  1. **Upload files**

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.
  1. **Finalize deployment**

The deployment is finalized and promoted to live. Your docs are available
    immediately at `your-slug.blode.md`.

## Project auto-creation

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...
```

## File handling

The CLI applies these rules when collecting files:

- **Skipped entries**: any file or directory starting with `.` (e.g., `.git`, `.env`) and `node_modules`
- **All other files**: included regardless of extension (MDX, JSON, images, fonts, etc.)
- **Batch size**: files are uploaded in batches of up to 4 MB each
- **Content types**: text files (MDX, JSON, YAML, CSS, JS, HTML, SVG) are uploaded with their correct MIME type; all others use `application/octet-stream`

## Branch resolution

The branch name is resolved in this order:

1. `--branch` flag
2. `BLODEMD_BRANCH` environment variable
3. `GITHUB_REF_NAME` environment variable (auto-set by GitHub Actions)
4. Current git branch (`git rev-parse --abbrev-ref HEAD`)
5. Falls back to `main`

## Commit message resolution

The commit message is resolved in this order:

1. `--message` flag
2. `BLODEMD_COMMIT_MESSAGE` environment variable
3. Latest git commit message (`git log -1 --pretty=%s`)

## Related pages

- [docs.json reference](/configuration/docs-json) -- configuration file format