> ## Documentation Index
> Fetch the complete documentation index at: https://modal-devin.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Command-line reference

> Complete reference for modal-devin init, deploy, destroy, doctor, and global options.

For first-time setup, use the interactive wizard:

```bash theme={null}
uvx modal-devin init
```

It guides you through Modal configuration, outpost and Secret creation, application
generation, and deployment. The commands and options below are reference material
for operating or automating an existing installation, not additional setup paths.

## Global commands

| Command        | Purpose                                                                           |
| -------------- | --------------------------------------------------------------------------------- |
| `init`         | Create a Devin outpost, Modal Secret, generated Modal application, and deployment |
| `deploy`       | Deploy a generated outpost file through the current Python environment            |
| `destroy`      | Stop Modal applications and delete their Devin outposts                           |
| `doctor`       | Check local credentials, secret presence, and runtime compatibility               |
| `--help`, `-h` | Display help                                                                      |
| `--version`    | Display the installed application version                                         |

## `modal-devin init`

```text theme={null}
modal-devin init [OPTIONS] [NAME]
```

Generates one Python application in `OUTPOSTS_DIR`. In an interactive terminal, omitted inputs are prompted for. In scripts and CI, `NAME` is required.

### Arguments and options

<ParamField path="NAME" type="string">
  Human-readable Devin Outposts outpost name. It is also available as `--name`.
</ParamField>

<ParamField path="--api-url" type="string" default="https://api.beta.devinenterprise.com">
  Base Devin API URL. It must be an absolute HTTP or HTTPS URL without credentials, a query string, or a fragment.
</ParamField>

<ParamField path="--secret-name" type="string" default="devin-outposts-token">
  Name of the [Modal Secret](https://modal.com/docs/guide/secrets) attached to both
  generated functions. The Secret must expose `DEVIN_OUTPOSTS_TOKEN` containing the
  key for a dedicated, admin-scoped Enterprise service user.
</ParamField>

<ParamField path="--outposts-dir" type="path" default="outposts">
  Directory for the generated Python file. Parent directories are created as needed.
</ParamField>

<ParamField path="--deploy / --no-deploy" type="boolean">
  Deploy or skip deployment after generation. The wizard prompts in interactive use;
  non-interactive use skips deployment when this option is omitted.
</ParamField>

### Output filename

The name becomes a safe lowercase Python module stem:

* Non-ASCII-alphanumeric and non-underscore runs become `_`.
* Leading and trailing underscores are removed.
* A name beginning with a digit gains the `outpost_` prefix.
* A name with no ASCII letter or digit is rejected.

For example, `Frontend / Prod` becomes `outposts/frontend_prod.py`.

### Interactive setup

Depending on answers and existing state, the wizard may:

1. Run `modal setup` and create an outpost through `POST /opbeta/outposts` on the Devin Outposts API.
2. Create a named Modal Secret directly through the Modal SDK.
3. Write the generated application and optionally deploy it with Modal.

The credential stays in memory during Secret creation rather than appearing in a
subprocess argument or local file.

### Setup safety

* `init` refuses to overwrite an existing output file.
* It validates the output path before creating remote resources.
* If setup cannot finish, it reports any remote resource that may require cleanup.

### Examples

```bash theme={null}
uvx modal-devin init
```

## `modal-devin deploy`

```text theme={null}
modal-devin deploy [OUTPOST-FILE] [--outposts-dir DIR]
```

Deployments always use Modal's `rolling` strategy so active session invocations drain
on their existing application version instead of being terminated by the update.

<ParamField path="OUTPOST-FILE" type="path">
  Generated or handwritten Modal outpost application to deploy. Omit it to deploy
  every `*.py` file found directly in `--outposts-dir` instead.
</ParamField>

<ParamField path="--outposts-dir" type="path" default="outposts">
  Directory to scan for outpost files when `OUTPOST-FILE` is omitted.
</ParamField>

The command deploys the selected application with the same project environment that
runs `modal-devin`. A failed Modal deployment produces a nonzero exit status.

When deploying a single file:

```bash theme={null}
uv run modal-devin deploy outposts/my_outpost.py
```

When deploying every outpost in a directory, each file is deployed sequentially even if an
earlier one fails; the command exits nonzero afterward and lists every outpost that
failed:

```bash theme={null}
uv run modal-devin deploy
uv run modal-devin deploy --outposts-dir deployments
```

## `modal-devin destroy`

```text theme={null}
modal-devin destroy [OUTPOST-FILE] [--outposts-dir DIR] [--yes]
```

`destroy` permanently stops each selected Modal application and deletes its Devin
outpost. Stopping a Modal application immediately terminates its running containers,
including active session invocations.

<ParamField path="OUTPOST-FILE" type="path">
  Generated or handwritten Modal outpost application to tear down. Omit it to use
  every `*.py` file found directly in `--outposts-dir`.
</ParamField>

<ParamField path="--outposts-dir" type="path" default="outposts">
  Directory to scan for outpost files when `OUTPOST-FILE` is omitted.
</ParamField>

<ParamField path="--yes, -y" type="boolean" default="false">
  Skip the destructive-action confirmation. This option is required when stdin or
  stdout is not an interactive terminal.
</ParamField>

Set `DEVIN_OUTPOSTS_TOKEN` to an admin-scoped Enterprise service user key before
running non-interactively. Interactive use prompts for the key if the environment
variable is absent. The command reads each file's literal `Worker.from_env(...)`
arguments without executing the file, then:

1. Stops the matching deployed Modal app. An app that is not deployed is already in
   the desired state.
2. Deletes the Devin outpost only after the Modal app was stopped or found absent.

All selected files are validated before any remote resource is changed. If a Modal
lookup or stop fails, the linked Devin outpost is preserved so the running scheduler
is not orphaned. The command continues across other selected files and reports all
failures with a nonzero exit status.

Generated files and Modal Secrets are deliberately retained. They may be inspected,
archived, or removed separately after `destroy` succeeds.

```bash theme={null}
uv run modal-devin destroy outposts/my_outpost.py --yes
uv run modal-devin destroy --yes
```

## `modal-devin doctor`

```text theme={null}
modal-devin doctor [--secret-name NAME] [--outposts-dir DIR]
```

<ParamField path="--secret-name" type="string" default="devin-outposts-token">
  Modal Secret name to verify.
</ParamField>

<ParamField path="--outposts-dir" type="path" default="outposts">
  Directory to scan for outpost files to check for a matching deployed Modal app.
</ParamField>

The command checks:

| Check                                                                   | Failure effect |
| ----------------------------------------------------------------------- | -------------- |
| Installed Modal SDK is compatible with this runtime                     | Exit status 1  |
| Local Modal token is valid                                              | Exit status 1  |
| Modal secrets can be listed                                             | Exit status 1  |
| Named Modal Secret exists                                               | Exit status 1  |
| Each outpost file in `--outposts-dir` has a matching deployed Modal app | Exit status 1  |

The last check reads each outpost file's `Worker.from_env(...)` call to determine its
expected Modal app name, without executing the file, and looks it up with
`modal.App.lookup`. Files whose app name cannot be determined statically (for example,
heavily hand-edited files) print a warning instead of failing.

`doctor` has no local Devin CLI prerequisite: `init` creates the outpost directly,
and only the deployed worker image needs the Devin CLI at runtime.