Remotes

Introduction

A remote is a NiceTryBot control panel that the nicetrybot command on your laptop works with. Once you've added one, the control panel commands, such as nicetrybot domains add, run there instead of on the machine you're typing on.

Remotes work a lot like Git's: you may save as many as you like, such as one for production and one for staging, give each a short name, and switch between them. The command talks to each remote's MCP server over HTTPS, using an API token you create in that control panel.

Adding a Remote

Creating a Token

Every remote needs an API token. In the control panel, an administrator opens Admin → API tokens and creates one:

The token is shown once. The page also shows the exact nicetrybot remote add command for your control panel, ready to copy.

Saving the Remote

Pass your control panel's address to remote add. When you leave the scheme out, https:// is assumed:

nicetrybot remote add panel.example.com

The command asks for the token without showing it as you paste, checks it with the control panel, saves the remote, and makes it your current one:

Make a token at https://panel.example.com/admin/tokens (pick its abilities and how long it lasts).
API token:
✓ Saved panel.example.com (https://panel.example.com), team Acme, expires in 30 days. It's the current remote.

By default, a remote is named after its host. To give it a shorter name, put the name first:

nicetrybot remote add prod panel.example.com
nicetrybot remote add staging staging-panel.example.com

Listing Remotes

To list your saved remotes:

nicetrybot remote list

   NAME     URL                                TEAM  TOKEN
*  prod     https://panel.example.com          Acme  expires in 29 days
   staging  https://staging-panel.example.com  Acme  expired: nicetrybot remote auth

The * marks the current remote. To see just the current one, run nicetrybot remote on its own.

Switching Remotes

To make another remote the current one:

nicetrybot remote use staging

Running nicetrybot remote with a remote's name, or a control panel's address, does the same thing. If no saved remote has that address, the command adds one:

nicetrybot remote prod
nicetrybot remote staging-panel.example.com

To run a single command somewhere else without switching, use --remote:

nicetrybot domains --remote=staging

If you run the command on a NiceTryBot server that also has a current remote, --local runs a command on the server's own stack instead. To stop using remotes on that machine altogether, run:

nicetrybot remote use --local

The full order in which the command decides where to run is described in Where Commands Run.

Working With Several Teams

A token made for All my teams works on every team you're on, so one remote can look after all of them. When you add the remote, the command lists your teams and asks you to pick one:

✓ Saved prod (https://panel.example.com), no team picked yet (token for all teams), expires in 30 days. It's the current remote.
Its token works on all your teams (acme, globex). Pick the one to work on: nicetrybot team use SLUG

To list the teams, with a * beside the one in use, and to switch:

nicetrybot teams
nicetrybot team use globex

   SLUG    TEAM
*  acme    Acme
   globex  Globex

The remote remembers the team, including when you renew its token. Run nicetrybot team to see which team you're on. To run a single command on another team without switching, pass --team:

nicetrybot domains --team=acme

On every team, the token can only do what you can do there. A token with Add and change domains can't add domains to a team where you're a plain member. Teams you join later are included straight away, and teams you leave are gone straight away.

A token for one team keeps working on that team only. Naming another team gives an error that says which team the token is for.

Renewing a Token

API tokens always expire. When a remote's token has expired, create a new one in Admin → API tokens and give it to the remote. A token for all teams stays on the team you picked:

nicetrybot remote auth prod

Leave the name out to renew the current remote's token.

Removing a Remote

To forget a remote:

nicetrybot remote remove staging

This only removes the remote from your laptop. Its token keeps working until it expires, so if you're done with it, delete it in Admin → API tokens as well.

How Remotes Are Stored

Each remote is a small file in ~/.config/nicetrybot/remotes, holding the control panel's address, its token, its team (and whether the token works on all of them), and when the token expires. The directory and its files are readable only by you. If you set XDG_CONFIG_HOME, they live under that instead, and NICETRYBOT_CONFIG_DIR may point the command somewhere else entirely.

The token is sent only to the remote's own /mcp path, in an Authorization header. The command hands it to curl on standard input rather than on the command line, so other users on your machine can't see it in the process list.

Troubleshooting

The command says the remote "doesn't take that token". The token has expired or been deleted, its user is no longer an administrator or no longer on the team, or there's no NiceTryBot control panel at that address. Without a working token, the MCP server answers exactly as if it didn't exist, so the command can't tell which. Create a new token and run nicetrybot remote auth.

The command says the remote "has no" tool. The control panel runs an older release that doesn't have that tool yet, or your token isn't allowed to use it. nicetrybot tools lists what your token may use. Update the control panel with nicetrybot update, or create a token with the ability you need.

The command asks for jq. Install it with brew install jq on macOS, or apt-get install jq on Linux.