> ## Documentation Index
> Fetch the complete documentation index at: https://langchain-5e9cc07a-preview-ramonn-1789138246-3410f5f.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 compiles and deploys code-first [Managed Deep Agents](/langsmith/javascript/managed-deep-agents-overview).

It is included with the `managed-deepagents` npm package.

<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/javascript/managed-deep-agents-quickstart). For workflow guidance, see [Identity](/langsmith/javascript/managed-deep-agents-identity), [Memory](/langsmith/javascript/managed-deep-agents-memory), [Evals](/langsmith/javascript/managed-deep-agents-evals), [Custom tools](/langsmith/javascript/managed-deep-agents-tools), [Connections](/langsmith/javascript/managed-deep-agents-connections), [Custom middleware](/langsmith/javascript/managed-deep-agents-middleware), [Sandboxes](/langsmith/javascript/managed-deep-agents-sandboxes), [Channels](/langsmith/javascript/managed-deep-agents-channels), [Schedules](/langsmith/javascript/managed-deep-agents-schedules), and [Deploy an agent](/langsmith/javascript/managed-deep-agents-deploy).

## Install

`mda init` declares `managed-deepagents` as a project dependency, so run the `mda` binary from the project.

<CodeGroup>
  ```bash npm theme={null}
  npx managed-deepagents init my-agent
  cd my-agent
  npm install
  npx mda --version
  ```

  ```bash pnpm theme={null}
  pnpm dlx managed-deepagents init my-agent
  cd my-agent
  pnpm install
  pnpm exec mda --version
  ```

  ```bash bun theme={null}
  bunx managed-deepagents init my-agent
  cd my-agent
  bun install
  bunx mda --version
  ```
</CodeGroup>

The package provides agent, identity, schedule, and sandbox authoring APIs.

## 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 Managed Deep Agents project.                           |
| `mda build [path]`                         | Compile a project into a managed LangGraph app without deploying.            |
| `mda evals …`                              | Initialize a Harbor workspace and continue eval authoring in a coding agent. |
| `mda dev [path]`                           | Compile a project and run it on the local LangGraph dev server.              |
| `mda connections …`                        | Manage authentication for tools and MCP connectors.                          |
| `mda deploy [path]`                        | Compile, sync Context Hub context, upload, and deploy to LangSmith.          |
| `mda channels init slack`                  | Add a Slack channel declaration to the current project.                      |
| `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:

<CodeGroup>
  ```bash npm theme={null}
  npx managed-deepagents init my-agent
  ```

  ```bash pnpm theme={null}
  pnpm dlx managed-deepagents init my-agent
  ```

  ```bash bun theme={null}
  bunx managed-deepagents init my-agent
  ```
</CodeGroup>

| 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.                                                                   |
| `--channel slack`          | Initialize the agent with a Slack channel declaration. Repeatable; `--channels` is an alias.                 |

To include Slack in a new project:

<CodeGroup>
  ```bash npm theme={null}
  npx managed-deepagents init my-agent --channel slack
  ```

  ```bash pnpm theme={null}
  pnpm dlx managed-deepagents init my-agent --channel slack
  ```

  ```bash bun theme={null}
  bunx managed-deepagents init my-agent --channel slack
  ```
</CodeGroup>

The scaffold language comes from the package you run, not from the current directory: the npm package always writes a TypeScript project. A CLI installed from npm refuses a Python project.

The scaffold creates:

| File              | Description                                                  |
| ----------------- | ------------------------------------------------------------ |
| `agent.ts`        | Named `agent` export from `defineDeepAgent(...)`.            |
| `instructions.md` | Managed system prompt.                                       |
| `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.    |

Eval tasks are opt-in and are not created by `mda init`. Run `mda evals init -i` from the project root to initialize the Harbor workspace and continue in a coding agent with the `eval-engineering` skill.

## Initialize a Slack channel

Run the following command from the root of an existing managed deep agent project:

<CodeGroup>
  ```bash npm theme={null}
  npx mda channels init slack
  ```

  ```bash pnpm theme={null}
  pnpm exec mda channels init slack
  ```

  ```bash bun theme={null}
  bunx mda channels init slack
  ```
</CodeGroup>

The command creates a Slack channel declaration in the `channels/` directory. The next `mda deploy` sets up the resources the agent needs to appear in Slack. For the complete workflow, see [Connect a Managed Deep Agent to Slack](/langsmith/javascript/managed-deep-agents-channels-slack).

## Build projects

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

<CodeGroup>
  ```bash npm theme={null}
  npx mda build
  ```

  ```bash pnpm theme={null}
  pnpm exec mda build
  ```

  ```bash bun theme={null}
  bunx mda build
  ```
</CodeGroup>

| 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 init` to initialize a Harbor workspace. Use the interactive handoff to develop complete tasks with a coding agent and the `eval-engineering` skill.

<CodeGroup>
  ```bash npm theme={null}
  npx mda evals init -i
  ```

  ```bash pnpm theme={null}
  pnpm exec mda evals init -i
  ```

  ```bash bun theme={null}
  bunx mda evals init -i
  ```
</CodeGroup>

| Command or flag       | Use                                                                                                                                                           |
| --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `mda evals init`      | Create `evals/harbor-job.json` when missing and generate the Harbor adapter and runtime settings under `.mda/evals/`. Run this command from the project root. |
| `-i`, `--interactive` | Start a detected coding agent with the eval-engineering prompt, or copy the prompt for another agent.                                                         |

The handoff asks the coding agent to install the `eval-engineering` skill, inspect the managed agent, and write complete Harbor tasks under `evals/<task>/`. It also includes the pinned Harbor command that loads the MDA job plugin and LangSmith plugin.

`mda evals compile` is an internal command used by the Harbor job plugin. The plugin runs it when a Harbor job starts, so you do not compile eval artifacts separately.

For workflow guidance, see [Evals](/langsmith/javascript/managed-deep-agents-evals).

## Develop locally

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

<CodeGroup>
  ```bash npm theme={null}
  npx mda dev
  ```

  ```bash pnpm theme={null}
  pnpm exec mda dev
  ```

  ```bash bun theme={null}
  bunx mda dev
  ```
</CodeGroup>

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

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.

## Manage connections

A connection links a managed deep agent to an external service. The credential lives in the LangSmith workspace, so it rotates without a redeploy, and a user-owned connection resolves the credential of whoever called the agent. Tools and MCP connectors resolve connections at runtime with `connections.get(...)`.

Create connections in one of three modes: opaque secret (fixed API key), general OAuth (BYOT app from the catalog or custom endpoints), or MCP OAuth (discover and register from an MCP server URL). Use `mda connections` to manage these credentials in the current workspace.

| Command                         | Use                                                              |
| ------------------------------- | ---------------------------------------------------------------- |
| `mda connections catalog`       | List services with preconfigured OAuth settings.                 |
| `mda connections create <slug>` | Create an opaque secret, general OAuth, or MCP OAuth connection. |
| `mda connections list`          | List connection metadata for the workspace.                      |
| `mda connections get <slug>`    | Show metadata for one connection.                                |
| `mda connections delete <slug>` | Delete a connection and its stored material.                     |

The first argument to `mda connections create` is a slug, which is your name for the connection and the name code passes to `connections.get(...)`. Provider names go to `--oauth`.

The OAuth catalog saves you from looking up a provider's OAuth settings. When you pass a listed service to `--oauth`, the CLI supplies its authorization URL, token URL, token endpoint authentication method, authorization parameters, and default scopes, so you provide only your client ID and client secret. The catalog does not limit which providers you can use: for anything else, pass `--authorize-url` and `--token-url`. Catalog names include `github`, `google`, `linear`, `slack`, `atlassian`, and `notion-api`:

<CodeGroup>
  ```bash npm theme={null}
  npx mda connections catalog
  ```

  ```bash pnpm theme={null}
  pnpm exec mda connections catalog
  ```

  ```bash bun theme={null}
  bunx mda connections catalog
  ```
</CodeGroup>

Create an agent-owned API key for a custom Tavily tool:

<CodeGroup>
  ```bash npm theme={null}
  npx mda connections create organization-tavily --secret-from-env TAVILY_API_KEY
  ```

  ```bash pnpm theme={null}
  pnpm exec mda connections create organization-tavily --secret-from-env TAVILY_API_KEY
  ```

  ```bash bun theme={null}
  bunx mda connections create organization-tavily --secret-from-env TAVILY_API_KEY
  ```
</CodeGroup>

The following flags control connection creation:

| Flag                              | Use                                                                                                                               |
| --------------------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| `--project PATH`                  | Set the project directory. Defaults to the current directory.                                                                     |
| `--workspace-id WORKSPACE_ID`     | Override `LANGSMITH_WORKSPACE_ID`.                                                                                                |
| `--secret-from-env VAR`           | Read a fixed value or OAuth client secret from the shell or project `.env`.                                                       |
| `--secret-from-file PATH`         | Read a fixed value or OAuth client secret from a file.                                                                            |
| `--oauth SERVICE`                 | Use the preconfigured settings for a service in `mda connections catalog`.                                                        |
| `--client-id CLIENT_ID`           | Set the OAuth client ID.                                                                                                          |
| `--auth-method METHOD`            | Set the token endpoint method to `client_secret_basic`, `client_secret_post`, or `none`.                                          |
| `--scope SCOPE`                   | Replace the provider's default scopes. Repeat for each scope.                                                                     |
| `--allowed-scope SCOPE`           | Set the maximum scope that an authorization flow can request. Repeat for each scope.                                              |
| `--authorization-param KEY=VALUE` | Add an OAuth authorization query parameter. Repeat for each parameter.                                                            |
| `--authorize-url URL`             | Set a custom OAuth authorization endpoint. Requires `--token-url`.                                                                |
| `--token-url URL`                 | Set a custom OAuth token endpoint. Requires `--authorize-url`.                                                                    |
| `--mcp URL`                       | Create an MCP OAuth connection by discovering OAuth from the MCP server URL.                                                      |
| `--authorize`                     | Sign in to the account the deployed agent uses, storing an agent-owned OAuth grant. Requires OAuth flags and a project directory. |

With no value flags and no `--oauth` endpoints, `mda connections create <slug>` infers MCP OAuth when that slug matches exactly one user-owned MCP connection in the project.

Use `--json` with `catalog`, `list`, or `get` for machine-readable output. Use `--yes` with `delete` to skip the confirmation prompt.

For credential owners, create modes, caller identity, and runtime examples, see [Manage connections](/langsmith/javascript/managed-deep-agents-connections).

## Deploy projects

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

<CodeGroup>
  ```bash npm theme={null}
  npx mda deploy
  ```

  ```bash pnpm theme={null}
  pnpm exec mda deploy
  ```

  ```bash bun theme={null}
  bunx mda deploy
  ```
</CodeGroup>

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

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/` and `channels/` 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.
11. Provision the declared Slack channel. If Slack authorization or workspace approval is required, display the action and continue after you complete it.

A project with a Slack channel cannot use `--no-wait` because Slack provisioning requires the deployed Agent Server URL. For the complete workflow, see [Connect a Managed Deep Agent to Slack](/langsmith/javascript/managed-deep-agents-channels-slack).

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

## Read deployment logs

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

<CodeGroup>
  ```bash npm theme={null}
  npx mda logs
  ```

  ```bash pnpm theme={null}
  pnpm exec mda logs
  ```

  ```bash bun theme={null}
  bunx mda logs
  ```
</CodeGroup>

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

<CodeGroup>
  ```bash npm theme={null}
  npx mda delete
  ```

  ```bash pnpm theme={null}
  pnpm exec mda delete
  ```

  ```bash bun theme={null}
  bunx mda delete
  ```
</CodeGroup>

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

## 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` or `agent.tsx` at the project root.                                                                                   |
| `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 deployments access. See [Pricing plans](/langsmith/pricing-plans).                   |
| 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>