NiceTryBot CLI

Introduction

NiceTryBot ships with a nicetrybot command that looks after your installation and works with your control panel, on your server or from your laptop. It does two jobs:

The control panel commands are calls to the same tools the MCP server gives agents, so the command, the control panel, and your agent all follow the same rules. A domain the command adds is checked exactly like one added in the control panel.

Installing the Command

On Your Server

The installer puts nicetrybot in /usr/local/bin, and every nicetrybot update replaces it with the copy that ships with the new release. There's nothing else to install.

On Your Laptop

The same command runs on macOS and Linux, where it works with your control panel over HTTPS. It needs curl and jq. macOS 15 and newer ship with both; on older versions, install jq using brew install jq.

Download the command from the newest release and make it executable:

mkdir -p ~/.local/bin

curl -fsSL https://github.com/NiceTryBot/nicetrybot/releases/latest/download/nicetrybot \
  -o ~/.local/bin/nicetrybot

chmod +x ~/.local/bin/nicetrybot

Make sure ~/.local/bin is on your PATH, then connect the command to your control panel by adding a remote:

nicetrybot remote add panel.example.com

Updating the Command

To update the command on your laptop to the newest release:

nicetrybot cli update

It downloads the release's copy, checks that it's a complete, working script, and only then swaps it in place of the old one. If you installed the command somewhere only root may write, run it with sudo. To go to a specific release, pass --version=vX.Y.Z. nicetrybot self-update does the same thing.

To see which release your copy came from, and whether a newer one is out:

nicetrybot cli version

On your server, there's no need: nicetrybot update updates NiceTryBot and the command together, so they always come from the same release.

Managing Your Server

These commands only ever work on the server they run on. Run them as root, or with sudo:

The stack lives in /opt/nicetrybot, unless the installer was told to put it somewhere else, in which case /etc/default/nicetrybot says where.

Working With the Control Panel

The following commands work on your server or, from your laptop, on a remote. To check who the commands act as, run whoami:

nicetrybot whoami

It prints the team, the user, what the commands are allowed to do, and when the token expires.

With a token for all of your teams, nicetrybot teams lists them and nicetrybot team use SLUG picks the one the commands work on. See Working With Several Teams.

Domains

To list your team's domains:

nicetrybot domains

HOSTNAME           MODE     STATUS                DNS   ORIGIN
docs.example.com   observe  pending_verification  -     https://docs-origin.example.com
shop.example.com   enforce  active                edge  https://shop-origin.example.com

To add a domain, give the hostname visitors type and the origin it should forward to. An origin without a scheme is assumed to use https://:

nicetrybot domains add docs.example.com docs-origin.example.com

Adding a domain prints the three steps that finish setup, in order: the ownership TXT record to add, the X-NiceTry-Origin-Secret header to lock your origin to so nobody can reach your site around the edge, and the DNS records that point at the edge. As in the control panel, nothing changes for your visitors until the domain is verified and its DNS points at the edge.

As you work through them, nicetrybot domains check shows where the domain stands. It looks up the TXT record, and verifies the domain as soon as the record appears. It then asks the origin whether it refuses requests without the header, and checks where public DNS points:

✓ Ownership: Found the TXT record: the domain is verified.
✗ Origin locked to the edge: The origin served a request without the secret header (200), so anyone can go around the edge.
     The header, and how to lock the origin: nicetrybot domains secret docs.example.com
✗ DNS at the edge: No records found for docs.example.com yet.
     CNAME  docs.example.com  edge.example.net

Next: lock the origin (nicetrybot domains secret docs.example.com), then check again.

You may pass the same settings as the Add domain modal:

For example, to put a site hosted on a platform that routes by Host header behind NiceTryBot:

nicetrybot domains add docs.example.com docs-edge.example.com \
  --host-header=rewrite \
  --forwarded-host-header=X-Forwarded-Host

Hosting Platforms has the exact command for Laravel Vapor, CloudFront, Vercel, and more. nicetrybot add domain and nicetrybot domain add work too, as do --rewrite-to-origin-host and --fwd-host-header in place of the longer options.

The rest of a domain's life happens one command at a time:

nicetrybot domains check docs.example.com            # Ownership, the origin lock and DNS, and the next step
nicetrybot domains verify docs.example.com           # Check only the ownership TXT record
nicetrybot domains secret docs.example.com           # The origin secret header, and how to lock the origin to it
nicetrybot domains mode docs.example.com enforce     # off, observe or enforce
nicetrybot domains remove docs.example.com           # Take the domain out of NiceTryBot

Rules and Gyms

To list your team's rules and gyms, or to delete one by its ID:

nicetrybot rules
nicetrybot rules 12          # Just rule 12
nicetrybot rules remove 12

nicetrybot gyms
nicetrybot gyms remove 4

Deleting asks for confirmation first, unless you pass --yes. To create or change rules and gyms, use the control panel, an agent, or any tool.

Calling Any Tool

Every tool the MCP server offers is available from the command line, including those your add-ons add. To list the tools your token may use:

nicetrybot tools

Then call one with call, passing its arguments as key=value pairs:

nicetrybot call query-traffic group_by=country period=7d
nicetrybot call backtest-rule source="TAG ip, ja4 AS 'dutch' FOR 1 DAY WHERE country = 'NL'" days=3

A value that reads as JSON, such as a number, true, or a list, is sent as that; anything else is sent as a string. You may also pass the arguments as a single JSON object:

nicetrybot call backtest-rule '{"id": 12, "days": 3}'

Add --json to see a tool's whole answer exactly as it sent it.

Where Commands Run

The control panel commands run in the first of these places that applies:

On a terminal, the command prints where it's working before it does anything, such as → prod (https://panel.example.com), team Acme, so a change never lands somewhere you didn't expect.

On your server, the command acts as the owner of the first administrator's current team, with every ability. Being able to run commands as root on the server is all the permission it needs. To work on another team, pass its slug:

nicetrybot domains --team=acme

Options

To see every command, run nicetrybot help.

Scripting

Every control panel command accepts --json, which prints the tool's answer as JSON for jq or your own scripts:

nicetrybot domains --json | jq -r '.domains[] | select(.protection_mode == "observe") | .hostname'

The command exits with a non-zero status when anything goes wrong, such as a validation error, a domain that doesn't exist, or a token that no longer works, and prints the reason to standard error.

Using the Command With AI

The command is a good fit for agents working in a terminal, since every answer explains itself and --json is there when they want structure. You may give your agent a prompt like the following:

Read https://docs.nicetrybot.com/docs/0.x/cli.md. Use the nicetrybot command to list my domains and tell me which ones are still in observe mode. Don't add, change, or remove anything until I say so.

If your agent supports MCP, you may connect it to the MCP server directly instead. It offers the same tools.