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

# edda push

Deploy your local MDX docs to Edda with edda push, using a browser session locally or a project deploy key in CI pipelines.

Upload your documentation files and publish them to Edda in a single command.

```bash
edda push [dir]
```

Authenticate once with `edda login` first. The CLI uses your browser GitHub session for local deploys. For CI, use a project deploy key in `BLODEMD_API_KEY`: see [Continuous deployment](/deployment/ci).

## Directory resolution

If you omit the `dir` argument, the CLI searches for a `docs.json` file in these locations (in order):

1. The current working directory
2. `./docs`
3. `./apps/docs`

If none contain a `docs.json`, the current directory is used.

## Options

- `--project <slug>` (type: string): Project slug. Falls back to the BLODEMD_PROJECT environment variable, then docs.json `slug`.
- `--api-key <token>` (type: string): Project deploy key for CI. Falls back to the BLODEMD_API_KEY environment variable, then stored credentials from `edda login`.
- `--api-url <url>` (type: string, default: "https://api.blode.md"): API base URL.
- `--branch <name>` (type: string, default: "main"): Git branch name attached to the deployment. Auto-detected from git if not provided.
- `--message <msg>` (type: string): Deploy message. Auto-detected from the latest git commit if not provided.

## Deployment flow

When you run `edda push`, the CLI executes these steps:

  1. **Validate configuration**

Reads and parses `docs.json` from the resolved docs directory.
  1. **Collect files**

Recursively collects all files in the directory. Dotfiles and `node_modules`
are skipped automatically.
  1. **Create deployment**

Sends a request to the Edda API to create a new deployment record with the
branch and commit message.
  1. **Upload files**

Uploads files in batches of up to 4 MB each. Large documentation sets are
split across multiple requests.
  1. **Finalize and promote**

The CLI marks the deployment as complete and promotes it to production. Your
docs are live immediately.

## Auto-create projects

If the project slug does not match an existing project, the CLI prompts you to create one using your authenticated GitHub session.

## Examples

```bash title="Push from default location"
edda push
```

```bash title="Push a specific directory"
edda push ./my-docs
```

```bash title="Push with explicit project and branch"
edda push --project my-project --branch staging
```

## Deploying from CI

Prefer not to run the CLI at all? Install the **Edda GitHub App** from the project Git tab in the dashboard. Pushes to your configured branch deploy automatically: no CLI, no tokens, no workflows. This is the recommended default.

To run the deploy yourself from GitHub Actions or another CI provider, use a project deploy key in `BLODEMD_API_KEY`. See [Continuous deployment](/deployment/ci).

## Skipped files

The CLI skips the following entries during file collection:

- Files and directories starting with `.` (dotfiles)
- The `node_modules` directory

## Related pages

- [edda login](/cli/login) -- authenticate before your first push
- [edda validate](/cli/validate) -- fail fast on config errors
- [Continuous deployment](/deployment/ci) -- deploy from CI with a project key