> ## Documentation Index
> [HTML page](https://blode.md/docs/deployment/push)
> [Documentation index](https://blode.md/docs/llms.txt)
> Use the index to discover all available pages before exploring further.

# Deploying with push

Deploy your MDX docs to Edda with edda push, including project slug resolution, API key auth, directory options, and what happens during upload.

You deploy documentation to Edda by running `edda push`. This page covers the command options, how directory resolution works, and what happens during a deployment.

## Command

```bash
edda 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., `edda push my-docs`), the CLI uses
>   that path directly without searching.

## What happens during a push

When you run `edda 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 `edda
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 Edda, the CLI offers to create it for you. This only works when you are logged in with browser OAuth (via `edda 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...
```

See [Continuous deployment](/deployment/ci) for how to use this key in GitHub Actions or another CI provider.

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