> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ooneex.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Remove a microservice

> Delete a microservice module and unregister it from every place create wired it in.

Removing a microservice is the exact inverse of creating one. The generator deletes the module's directory under `modules/<name>/` and then unwinds every registration that brought it into the app — the app module, the shared module, the app config, the env config, docker-compose, the tsconfig path aliases, and the commitlint config. When it finishes, no trace of the microservice is left in the project.

This is a one-command operation. You name the microservice, confirm, and the generator does the rest.

## What it does

The command works against an existing microservice. It will not create anything, and it refuses to touch the two built-in modules:

* The `app` and `shared` modules **cannot** be removed — they are part of every project.
* A name that does not match an existing microservice is reported as an error.
* You are asked to **confirm** before anything is deleted, unless you pass `--silent`.

Once confirmed, the generator unregisters the microservice everywhere (see the list below) and finally deletes the `modules/<kebab-name>/` directory.

## CLI command

Run the generator from your project. With no flags it prompts for the name and then asks you to confirm.

```bash theme={null}
ooneex microservice:remove [options]
```

```bash theme={null}
# Interactive: prompts for the name, then confirms
ooneex microservice:remove

# Provide the name as a flag
ooneex microservice:remove --name=billing

# Run against a specific project directory
ooneex microservice:remove --name=billing --cwd=/path/to/project
```

| Option     | Description                                                                                                                            | Default                   |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
| `--name`   | Microservice name to remove. Normalized to PascalCase with any trailing `Module` stripped; the module folder uses its kebab-case form. | Prompted if omitted       |
| `--cwd`    | Project directory the microservice is removed from.                                                                                    | Current working directory |
| `--silent` | Suppress the confirmation prompt and output.                                                                                           | `false`                   |

<Warning>
  This is destructive. The command deletes the entire `modules/<name>/` directory — all controllers, services, entities, tests, and anything else inside it — and removes every reference to the microservice across the project. There is no undo. Commit or branch first so the change is reviewable and reversible through git. The `app` and `shared` modules are protected and cannot be removed, and you will be asked to confirm before deletion unless you pass `--silent`.
</Warning>

## What gets unregistered

Every wiring step that [create](/microservice/create) performs is reversed:

* **App module (`AppModule`)** — the microservice's module registration is removed.
* **Shared module (`SharedModule`)** — the microservice is unregistered.
* **App config (`modules/app/app.yml`)** — the entry is removed from the `microservices:` list.
* **Env config (`.env.yml`)** — the `microservices:` entry is removed.
* **Docker Compose (`docker-compose.yml`)** — the app's service block for the microservice is deleted.
* **TypeScript config (root `tsconfig.json`)** — the microservice's path aliases are removed.
* **Commitlint config** — the microservice is dropped from the allowed scopes.

After all of the above, the `modules/<kebab-name>/` directory itself is deleted.

## Use with Claude and Codex

The generator ships a matching `microservice:remove` skill. It runs the command and walks your AI agent through confirming the removal and verifying that the wiring is gone. Initialize the skills once for your agent:

<Tabs>
  <Tab title="Claude">
    ```bash theme={null}
    ooneex claude:init
    ```

    Then ask Claude in natural language — it maps the request to the generator and runs it:

    ```text Prompt icon="terminal" wrap theme={null}
    Remove the billing microservice from this project.
    ```
  </Tab>

  <Tab title="Codex">
    ```bash theme={null}
    ooneex codex:init
    ```

    Then ask Codex in natural language — it maps the request to the generator and runs it:

    ```text Prompt icon="terminal" wrap theme={null}
    Remove the billing microservice from this project.
    ```
  </Tab>
</Tabs>

For example, the prompt above maps to `microservice:remove --name=billing`, then confirms the deletion when asked.

## Related

* [Microservices overview](/microservice/overview) — what a microservice is and how it fits the project.
* [Create](/microservice/create) — scaffold a new microservice and wire it in.
* [Networking](/microservice/networking) — how microservices reach each other at runtime.
* [microservice:remove](/cli/commands/microservice-remove) — the full command reference.