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

# Content moderation with the CLI

> Learn how to moderate content from your terminal, scripts and CI with the Moderation API CLI

***

<Snippet file="prerequisites.mdx" />

***

## 1. Install the CLI

```bash Homebrew theme={"theme":"nord"}
brew install moderation-api/tap/modapi
```

```bash macOS / Linux theme={"theme":"nord"}
curl -fsSL https://raw.githubusercontent.com/moderation-api/cli/main/scripts/install.sh | bash
```

```powershell Windows theme={"theme":"nord"}
iwr -useb https://raw.githubusercontent.com/moderation-api/cli/main/scripts/install.ps1 | iex
```

```bash Go theme={"theme":"nord"}
go install github.com/moderation-api/cli/cmd/modapi@latest
```

> [!NOTE]
>
> You can also download a binary for your platform from the [releases page](https://github.com/moderation-api/cli/releases).

## 2. Set up your project

Sign in with your Moderation API account, then run `init` in your project's directory:

```bash theme={"theme":"nord"}
modapi login   # once per computer; opens the browser
modapi init    # in your project's directory
```

`login` opens the browser, where you sign in and pick an organization. On a computer without a browser, such as over SSH, use `modapi login --device` and confirm a code on another device.

When your organization already has projects, `init` asks whether to link one of them or create a new one. It writes the project's keys to your env file: `MODAPI_SECRET_KEY` and `MODAPI_WEBHOOK_SECRET`, in `.env.local` for Next.js or `.env` otherwise. It also adds that file to `.gitignore`. Describe your platform, and the project suggests moderation policies for it:

```bash theme={"theme":"nord"}
modapi init --domain acme.com \
  --context "Marketplace where buyers and sellers chat before a booking" \
  --brief "Stop contact details shared outside the platform, scams and harassment"
```

If the env file already has a working `MODAPI_SECRET_KEY`, `init` changes nothing. Add `--dry-run` to see what it would do.

To connect a directory to a project you already have, run `modapi link`, or name the project:

```bash theme={"theme":"nord"}
modapi link "Acme Marketplace"
```

Linking makes a new key for the project, named after your computer and directory, so you can revoke it on its own. In scripts and coding agents, pass `init --project <id or name>` to link or `init --new` to create, instead of answering the question.

Check the setup at any time with `modapi doctor`. It checks the key against the API, the webhook secret, `.gitignore` and the SDK dependency, and says how to fix each problem it finds.

> [!TIP]
>
> Already have a project? Set its API key in the `MODAPI_SECRET_KEY` environment variable instead, or run `modapi configure` to store it in your operating system's keychain. In CI, skip `login` and set `MODAPI_ORGANIZATION_KEY` to an [organization key](https://docs.moderationapi.com/api-reference/management-api.md).

### Let your coding agent add moderation

`init` does not change your code. To add the moderation calls, install the setup skill for your coding agent:

```bash theme={"theme":"nord"}
npx skills add moderation-api/skills
```

Then ask your agent to "set up Moderation API". The skill finds where users create content, adds the moderation call, handles the result and sets up webhooks. It asks you before each change. See [Setup skill](https://docs.moderationapi.com/ai/skill.md).

## 3. Submit content

Use `modapi content submit` to moderate text, images, video, audio, or objects with several fields. Only `--content` is required.

```bash Text moderation theme={"theme":"nord"}
modapi content submit \
  --content '{"type":"text","text":"Hello world!"}' \
  --content-id message-123 \
  --author-id user-123 \
  --conversation-id room-456 \
  --metadata '{"customField":"value"}'
```

```bash Image moderation theme={"theme":"nord"}
modapi content submit \
  --content '{"type":"image","url":"https://example.com/image.jpg"}' \
  --content-id image-456 \
  --author-id user-123
```

```bash Object moderation theme={"theme":"nord"}
modapi content submit \
  --content '{"type":"object","data":{"title":{"type":"text","text":"Post title"},"body":{"type":"text","text":"Post content"},"thumbnail":{"type":"image","url":"https://example.com/thumb.jpg"}}}' \
  --content-id post-789 \
  --author-id user-123
```

## 4. Use the result

Use `--jq` to read one field of the result. For example, get the recommended action (`allow`, `review` or `reject`). Add `--raw-output` to print the value as plain text:

```bash theme={"theme":"nord"}
action=$(modapi content submit \
  --content '{"type":"text","text":"Hello world!"}' \
  --jq '.recommendation.action' --raw-output)

if [ "$action" = "reject" ]; then
  echo "Content rejected"
fi
```

For the full result as JSON, use `--output-format json`.

## 5. Preview a request

Add `--dry-run` to any command to see the request it would send. The CLI does not send the request, so it does not use your quota:

```bash theme={"theme":"nord"}
modapi content submit --content '{"type":"text","text":"Hello world!"}' --dry-run
```

## 6. Explore other commands

The CLI has a command for each API endpoint. Some examples:

```bash theme={"theme":"nord"}
# List authors
modapi authors list

# Get every page of moderation actions as JSON, one item per line
modapi actions list --all --output-format json

# Get the webhook signing secret
modapi webhook-secret retrieve

# Show all commands, or the flags of one command
modapi --help
modapi content submit --help
```

If a command fails, it exits with a code that is not `0`: `1` for API errors, `2` for usage errors and `3` for authentication errors.

### Organization key

Commands for projects and channels (`modapi projects` and `modapi channels`) use the [management API](https://docs.moderationapi.com/api-reference/management-api.md) and need an organization key. To run them while `MODAPI_SECRET_KEY` holds your project key, pass the organization key with `--secret-key`:

```bash theme={"theme":"nord"}
modapi projects list --secret-key "$MODAPI_ORGANIZATION_KEY"
```

An organization key can also run the other commands for a project: name it with `--project-id`.

```bash theme={"theme":"nord"}
modapi authors list --secret-key "$MODAPI_ORGANIZATION_KEY" --project-id "$PROJECT_ID"
```

***

<Snippet file="dry-run.mdx" />

***

<Snippet file="review-flagged.mdx" />

***

<Snippet file="all-done.mdx" />