Content moderation with the CLI

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

---

Prerequisites

You'll need an API key to use the Moderation API. To get one, you'll need to create a project.

• Create a project

---

1. Install the CLI

Homebrew

brew install moderation-api/tap/modapi

You can also download a binary for your platform from the releases page.

2. Set up your project

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

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:

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:

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.

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.

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:

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.

3. Submit content

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

Text moderation

modapi content submit \
  --content '{"type":"text","text":"Hello world!"}' \
  --content-id message-123 \
  --author-id user-123 \
  --conversation-id room-456 \
  --metadata '{"customField":"value"}'

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:

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:

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:

# 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 and need an organization key. To run them while MODAPI_SECRET_KEY holds your project key, pass the organization key with --secret-key:

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.

modapi authors list --secret-key "$MODAPI_ORGANIZATION_KEY" --project-id "$PROJECT_ID"

---

Dry-run mode: If you want to analyze production data but don't want to block content, enable "dry-run" in your project settings.

With dry-run enabled, the API still analyzes content but it always returns flagged: false - yet content still shows in the review queue. This way you can implement your moderation workflows and start testing your project configuration without actually blocking content.

---

3. Review flagged content (optional)

If the AI flags the content, it will appear in the Review inbox.

Head to the review queue to validate that the content is submitted correctly.

Review queue for reviewing and improving automated moderation

You can use review queues to implement moderation workflows or simply check how the AI is performing.

---

All Done!

Congratulations! You've run your first moderation checks. Here are a few next steps:

• Continue tweaking your project settings and models to find the best moderation outcomes.
• Add custom Guidelines to a channel for rules specific to your platform.
• Explore advanced features like context-aware moderation.
• If you have questions, reach out to our support team.

We love hearing from you—please share how you're using the service and let us know if you have suggestions or need help. Happy moderating!