> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-harris-1786029617-6b0a55e.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Managed Deep Agents CLI reference

> Reference for mda commands, project files, and deploy behavior.

The `mda` CLI tests and deploys code-first [Managed Deep Agents](/langsmith/managed-deep-agents-overview). It is included with the `managed-deepagents` npm and Python packages.

<Note>
  Managed Deep Agents is in **public [beta](/langsmith/release-stages)** and available on [LangSmith Cloud](/langsmith/cloud) in the US region only.
</Note>

For the fastest end-to-end path, see the [quickstart](/langsmith/managed-deep-agents-quickstart). For workflow guidance, see [Identity](/langsmith/managed-deep-agents-identity), [Memory](/langsmith/managed-deep-agents-memory), [Evals](/langsmith/managed-deep-agents-evals), [Custom tools](/langsmith/managed-deep-agents-tools), [Custom middleware](/langsmith/managed-deep-agents-middleware), [Sandboxes](/langsmith/managed-deep-agents-sandboxes), [Channels](/langsmith/managed-deep-agents-channels), [Schedules](/langsmith/managed-deep-agents-schedules), and [Deploy an agent](/langsmith/managed-deep-agents-deploy).

## Install

Install the package for the language you use to author your agent. Both packages expose the `mda` binary. For npm, install globally or run the binary with `npm exec`.

<CodeGroup>
  ```bash uv theme={null}
  uv tool install --prerelease allow managed-deepagents
  ```

  ```bash npm theme={null}
  npm install -g managed-deepagents@dev
  ```
</CodeGroup>

For Python, `uv tool install --prerelease allow managed-deepagents` installs the `mda` CLI. A Python project generated by `mda init` has its own `pyproject.toml`; run `uv sync` inside that project to install project dependencies before local development or deploy.

The TypeScript package provides agent, identity, schedule, and sandbox authoring APIs. The Python package provides the same surfaces with snake-case names, plus the `mda` console script.

## Authentication

`mda deploy` reads API keys in this order:

1. `LANGGRAPH_HOST_API_KEY`
2. `LANGSMITH_API_KEY`
3. `LANGCHAIN_API_KEY`

The CLI reads those values from the project `.env` file first, then from the process environment. If no key is found in an interactive terminal, `mda deploy` prompts for a LangSmith API key and saves it to the project `.env` file.

```text .env theme={null}
LANGSMITH_API_KEY=<LANGSMITH_API_KEY>
OPENAI_API_KEY=<OPENAI_API_KEY>
```

To deploy with an organization-scoped key, set `LANGSMITH_WORKSPACE_ID` or pass `--workspace-id` to `mda deploy`.

The LangSmith API key authenticates the deploy. The agent's model provider also needs credentials at runtime. Set the provider key in `.env`, export it in your shell, or configure it as a LangSmith workspace secret. For example, `openai:gpt-5.5` requires `OPENAI_API_KEY`.

`mda deploy` forwards non-reserved `.env` entries, such as `OPENAI_API_KEY`, MCP tokens, and custom tool credentials, as hosted deployment secrets. Reserved platform variables, including `LANGSMITH_API_KEY`, `LANGGRAPH_HOST_API_KEY`, `LANGCHAIN_API_KEY`, and `LANGSMITH_WORKSPACE_ID`, are used for CLI authentication and deploy routing but are not uploaded as user-managed deployment secrets.

## Command overview

| Command                                    | Use                                                                 |
| ------------------------------------------ | ------------------------------------------------------------------- |
| `mda --help`                               | Show CLI help.                                                      |
| `mda --version`                            | Show the installed CLI version.                                     |
| `mda init <name>`                          | Scaffold a TypeScript or Python Managed Deep Agents project.        |
| `mda build [path]`                         | Compile a project into a managed LangGraph app without deploying.   |
| `mda eval …` / `mda evals …`               | Scaffold Harbor-style eval tasks and compile a Harbor handoff.      |
| `mda dev [path]`                           | Compile a project and run it on the local LangGraph dev server.     |
| `mda deploy [path]`                        | Compile, sync Context Hub context, upload, and deploy to LangSmith. |
| `mda logs [path]`                          | Tail Agent Server logs for a deployed agent.                        |
| `mda delete [path]` / `mda destroy [path]` | Delete a deployed agent and the LangSmith resources it created.     |

## Initialize projects

Use `mda init` to create a new project directory:

```bash theme={null}
mda init my-agent
```

| Argument or flag           | Use                                                                                                          |
| -------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `name`                     | Required project directory name. The command fails if the destination already exists.                        |
| `--instructions TEXT`      | System prompt to write into `instructions.md`.                                                               |
| `--instructions-file PATH` | Read the system prompt for `instructions.md` from a file, or from stdin when set to `-`.                     |
| `--identity`               | Add managed authentication with user-owned threads.                                                          |
| `--memory agent\|none`     | Optionally write a root memory declaration. If omitted, no memory file is created and durable memory is off. |
| `--model SPEC`             | Model the agent runs on, as `provider:model`.                                                                |
| `--no-sandbox`             | Leave out the managed sandbox declaration.                                                                   |

The command detects the language from the current directory:

| Current directory contains | Result                       |
| -------------------------- | ---------------------------- |
| `package.json` only        | TypeScript scaffold.         |
| `pyproject.toml` only      | Python scaffold.             |
| Both or neither            | Interactive language prompt. |

The scaffold creates:

| File                               | Description                                                                   |
| ---------------------------------- | ----------------------------------------------------------------------------- |
| `agent.py` or `agent.ts`           | Named `agent` export from `define_deep_agent(...)` or `defineDeepAgent(...)`. |
| `instructions.md`                  | Managed system prompt.                                                        |
| `pyproject.toml` or `package.json` | Minimal language-specific manifest.                                           |
| `README.md`                        | Local project instructions.                                                   |
| `.env`                             | Deploy auth and runtime secrets. Do not commit real secrets.                  |
| `.gitignore`                       | Ignores `.env`, `.env.*`, `.mda/`, and dependency caches.                     |
| `evals/`                           | Example Harbor-style eval tasks for Harbor trials.                            |

## Build projects

Use `mda build` to compile a project into a managed LangGraph app without deploying it:

```bash theme={null}
mda build .
```

| Argument or flag | Use                                                                                                                                                                                     |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `path`           | Project directory. Defaults to the current directory.                                                                                                                                   |
| `--out OUT`      | Output directory for the compiled app. Defaults to `<path>/.mda/build`. The directory is emptied before the build, so it must be missing, empty, or a directory a previous build wrote. |

## Evaluate projects

Use `mda evals` to scaffold Harbor-style tasks and compile a Harbor handoff. Harbor runs the trials:

```bash theme={null}
mda evals init
mda evals compile .
# then run the printed `harbor run` command
```

| Subcommand                 | Use                                                                            |
| -------------------------- | ------------------------------------------------------------------------------ |
| `mda evals init [path]`    | Scaffold the example `evals/` suite, or a single task directory.               |
| `mda evals compile [path]` | Compile the managed agent into `.mda/evals/` and print a `harbor run` command. |

`mda evals compile` flag:

| Flag                       | Use                                                                                                                               |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `--model <provider:model>` | Model for the example Harbor job config. Repeat to record a matrix in the artifact manifest; the job config uses the first value. |

For task layout, verifiers, identity fixtures, and running Harbor, see [Evals](/langsmith/managed-deep-agents-evals).

## Develop locally

Use `mda dev` to compile a project and run the local LangGraph dev server:

```bash theme={null}
mda dev .
```

| Argument or flag      | Use                                                                     |
| --------------------- | ----------------------------------------------------------------------- |
| `path`                | Project directory. Defaults to the current directory.                   |
| `--port PORT`         | Forward a port to the LangGraph dev server.                             |
| `--hostname HOSTNAME` | Forward a host to the LangGraph dev server.                             |
| `--no-browser`        | Prevent the dev server from opening Studio in a browser when it starts. |
| `--no-reload`         | Disable the dev server's hot reload.                                    |

`mda dev` compiles into `.mda/build`, then starts the language-specific LangGraph dev server from that directory:

| Project language | Dev server command                                         |
| ---------------- | ---------------------------------------------------------- |
| TypeScript       | `npx --yes @langchain/langgraph-cli dev`                   |
| Python           | `uv run --with langgraph-cli[inmem]>=0.4.30 langgraph dev` |

For Python projects, install `uv` before running `mda dev`. The CLI resolves the local LangGraph dev server automatically, so you do not need to install `langgraph-cli[inmem]` yourself.

When a sandbox is configured, `mda dev` tries the configured provider. If provider credentials are unavailable or provider creation fails, it falls back to a local temp-directory sandbox and prints the chosen path.

For local development, `mda dev` stages the project `.env` file into `.mda/build/.env` so LangGraph can load model provider keys and other runtime credentials.

## Deploy projects

Use `mda deploy` to compile and deploy a project to LangSmith:

```bash theme={null}
mda deploy .
```

| Argument or flag              | Use                                                                                   |
| ----------------------------- | ------------------------------------------------------------------------------------- |
| `path`                        | Project directory. Defaults to the current directory.                                 |
| `--name NAME`                 | Deployment name. Defaults to the agent `name` from `defineDeepAgent`.                 |
| `--deployment-type dev\|prod` | Deployment type when creating a deployment. Defaults to `dev`.                        |
| `--workspace-id WORKSPACE_ID` | Workspace ID to deploy into. Overrides `LANGSMITH_WORKSPACE_ID`.                      |
| `--no-wait`                   | Trigger the remote build and exit without polling for deployment completion.          |
| `--configure-slack`           | Generate bootstrap and deployed app manifests for the project's single Slack channel. |

Deploy runs these steps:

1. Validate the project directory and load the agent entry file.
2. Resolve the LangSmith API key and optional workspace ID.
3. Collect non-reserved `.env` values as hosted deployment secrets.
4. Verify the model provider API key is available from `.env`, the shell environment, or LangSmith workspace secrets.
5. Sync deploy-owned context to Context Hub.
6. Compile the project into `.mda/build` and extract optional `schedules/` declarations.
7. Create or find a LangSmith hosted deployment by name.
8. Archive the build, upload it, and trigger a remote build.
9. Poll the revision until it reaches `DEPLOYED` unless `--no-wait` is set.
10. Reconcile the managed LangSmith cron jobs for schedules unless `--no-wait` is set.

With `--configure-slack`, deploy requires exactly one Slack channel and a project-root `slack-app-manifest.json`. When the Slack credentials are missing, it writes `.mda/slack/bootstrap-manifest.json` and exits before changing remote state. After you create the app and add its credentials, rerun the waited deployment to write `.mda/slack/app-manifest.json` with the deployed Events URL. For the complete workflow, see [Slack channels](/langsmith/managed-deep-agents-channels-slack#create-and-deploy-the-slack-app).

On success, the CLI prints the LangSmith deployment dashboard URL. For secrets routing and deploy tips, see [Deploy an agent](/langsmith/managed-deep-agents-deploy).

## Read deployment logs

Use `mda logs` to tail Agent Server logs for a deployed agent:

```bash theme={null}
mda logs .
```

| Argument or flag              | Use                                                                                                   |
| ----------------------------- | ----------------------------------------------------------------------------------------------------- |
| `path`                        | Project directory. Defaults to the current directory.                                                 |
| `--name NAME`                 | Deployment name. Defaults to the agent `name` from the project.                                       |
| `--lines LINES`               | Number of recent log lines to fetch. Defaults to `1000`.                                              |
| `--level LEVEL`               | Only show entries at or above the given severity: `debug`, `info`, `warning`, `error`, or `critical`. |
| `--follow`                    | Keep streaming new logs. This is the default in an interactive terminal.                              |
| `--no-follow`                 | Print recent logs and exit. This is the default when output is piped.                                 |
| `--workspace-id WORKSPACE_ID` | Workspace ID to read from. Overrides `LANGSMITH_WORKSPACE_ID`.                                        |

## Delete deployments

Use `mda delete` to delete a deployed Managed Deep Agent and the LangSmith resources it created. `mda destroy` is an alias.

```bash theme={null}
mda delete .
```

| Argument or flag              | Use                                                                       |
| ----------------------------- | ------------------------------------------------------------------------- |
| `path`                        | Project directory. Defaults to the current directory.                     |
| `--name NAME`                 | Deployment name. Defaults to the agent `name` from `defineDeepAgent`.     |
| `--workspace-id WORKSPACE_ID` | Workspace ID the deployment lives in. Overrides `LANGSMITH_WORKSPACE_ID`. |
| `--yes`                       | Delete without asking for confirmation.                                   |

## Project files

For the required entry point, optional managed files, regular application modules, and excluded paths, see [Project structure](/langsmith/managed-deep-agents-project-structure).

## Agent definition

For the required export, model configuration, and core agent capabilities, see [Agent definition](/langsmith/managed-deep-agents-agent-definition).

## Troubleshooting

| Symptom                                              | Cause and fix                                                                                                                        |
| ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `project root ... is not a directory`                | Pass a directory path to `mda dev` or `mda deploy`.                                                                                  |
| `no agent entry file found`                          | Add `agent.ts`, `agent.tsx`, or `agent.py` at the project root.                                                                      |
| `mda dev` cannot find `uv`                           | For Python projects, install `uv` so `mda dev` can resolve the local LangGraph dev server.                                           |
| `No LangSmith API key found`                         | Set `LANGSMITH_API_KEY` or add it to the project `.env`.                                                                             |
| Deploy fails with 401 or 403                         | Confirm the API key belongs to a workspace with beta access.                                                                         |
| Deploy reports a missing model provider API key      | Add the provider key, such as `OPENAI_API_KEY`, to `.env`, export it in your shell, or configure it as a LangSmith workspace secret. |
| Deploy reports a Context Hub conflict                | The Context Hub repo changed during deploy. Re-run `mda deploy`.                                                                     |
| The build exceeds 200 MB                             | Remove generated artifacts or large files from the project before deploying.                                                         |
| Deployment reaches `BUILD_FAILED` or `DEPLOY_FAILED` | Open the printed deployment URL in LangSmith and inspect the revision logs.                                                          |

***

<div className="source-links">
  <Callout icon="terminal-2">
    [Connect these docs](/use-these-docs) to Claude, VSCode, and more via MCP for real-time answers.
  </Callout>

  <Callout icon="edit">
    [Edit this page on GitHub](https://github.com/langchain-ai/docs/edit/main/src/langsmith/managed-deep-agents-cli.mdx) or [file an issue](https://github.com/langchain-ai/docs/issues/new/choose).
  </Callout>
</div>