Skip to content
Administration
CLI Tools Reference

CLI Tools Reference

Every XUI.live server ships a command-line utility at /home/xui/tools. It exists for the moments the panel itself cannot help you — a lost password, a locked-out 2FA account, a firewall rule that blocked the wrong address — and for the two biggest operations an installation ever goes through: a factory reset and a migration from an older panel.

Run it as root, with no arguments, and it lists everything it can do:

sudo /home/xui/tools
rescue          Create a rescue access code for the admin panel.
user            Create a rescue admin user for the admin panel.
mysql           Reauthorise load balancers on MySQL.
database        Restore blank XUI database.
restore <file>  Migrate from old XUI backup. Ex: restore /path/to/backup.sql
flush           Flush blocked IP database.
2fa [user|all]  Disable/reset 2FA for a panel account (lockout rescue).
ports           Regenerate ports from SQL table.
access          Regenerate access codes from SQL table.

The tool runs as root, full stop — invoked as any other user it prints Please run as root! and exits, help screen included.

Getting back in

rescue — a temporary panel URL

Creates an access code named rescue, wires it into the web server and prints the resulting address:

sudo /home/xui/tools rescue
# Access: http://<server-ip>:<port>/rescue/

Use it when you have deleted or lost your access codes and the panel has no reachable URL left. The code routes to the admin panel for administrator accounts.

rescue is a well-known path. Sign in, create a proper access code of your own, and delete the rescue one — the tool reminds you, and it means it.

user — a temporary administrator

Creates an admin account named rescue with a freshly generated password and prints the credentials. If the Administrators group itself has been damaged or deleted, it is rebuilt first — this command works even on a panel whose permission system is broken.

sudo /home/xui/tools user
# Username: rescue
# Password: <generated>

The same rule applies: sign in, fix your real account, delete rescue.

2fa — two-factor lockout recovery

Lost the phone that held your authenticator? Run it bare to see which accounts have two-factor authentication enabled:

sudo /home/xui/tools 2fa

Then reset one account, or all of them:

sudo /home/xui/tools 2fa admin     # one account
sudo /home/xui/tools 2fa all      # every account

The reset clears the secret and the recovery codes entirely. The account signs in with username and password again, and can re-enable 2FA from Account in the panel.

Configuration regeneration

The panel stores its ports and access codes in the database; the web server reads them from generated configuration files. These two commands rebuild those files from what the database says — the fix for a configuration that has drifted out of sync or been edited by hand.

ports

Regenerates the HTTP, HTTPS and RTMP listener configuration from the server’s settings, prints the resulting port list and reloads the services:

sudo /home/xui/tools ports
# HTTP Ports: 80
# SSL Ports: 443
# RTMP Port: 8880

Use it after changing ports in the panel if the change does not appear to take, or after restoring a configuration backup.

access

Regenerates the access-code routing and prints every admin-panel URL currently active:

sudo /home/xui/tools access

mysql

Re-grants database access to every load balancer registered in the panel. Reach for it when an edge server starts refusing to authenticate against the main — typically after a database restore or a change of load balancer IP:

sudo /home/xui/tools mysql

Blocking

flush — unblock everything at once

Empties the blocked-IP table, removes the flood-protection block files, flushes the system firewall rules and reloads both web server instances:

sudo /home/xui/tools flush

This is the command for the day the panel’s flood protection catches something it should not — your own office IP, a reseller’s network, a monitoring probe. It clears all blocks, so anything you still want blocked has to be re-added afterwards.

The big two

database — factory reset

Drops the panel database and rebuilds it from the blank schema, exactly as a fresh installation would: the server’s IP and network interfaces are re-detected, ports return to 80, 443 and 8880, the PHP workers are rebuilt, services restart, and a rescue access code plus a rescue administrator are created so you can get straight back in.

sudo /home/xui/tools database
# Access: http://<server-ip>/rescue/
# Username: rescue
# Password: <generated>
This erases everything — subscribers, streams, resellers, history, settings. There is no confirmation prompt and no undo. If there is any chance you will want the current data back, take a backup first.

restore <file> — migrate from an older XUI backup

The migration path from an earlier XUI installation. Point it at a .sql backup of the old panel and it imports the content — subscribers, streams, movies, series, bouquets, categories, packages, resellers, devices, EPG sources, providers, blocking rules, tickets — while keeping the current installation’s schema and settings intact.

sudo /home/xui/tools restore /root/old-panel-backup.sql

The file must be a plain .sql dump — anything else is rejected before a single byte is touched.

It runs as seven visible steps, and the order is the safety story:

  1. A safety backup of the current database is taken first, into /home/xui/backups/. The rollback command is printed at the end if anything looks wrong.
  2. The old backup loads into a temporary database — your live data is not touched while it parses.
  3. Services stop.
  4. Content tables import with automatic column mapping: columns that no longer exist are ignored, columns new to this version take their defaults. Settings, server definitions and runtime data are deliberately not imported — your current installation keeps its own.
  5. Every stream is set to stopped, and stale runtime state — live sessions, queued jobs, cached files — is cleared.
  6. Row counts are verified old-against-new, table by table, and printed.
  7. The temporary database is removed, services restart, and a rescue access code is created for your first sign-in.

After it finishes, start your streams from the panel and work through the imported content at your own pace. Nothing is running that you did not start yourself.

When something is not right

Every command prints what it did. If an operation warns, the message includes the exact path of the safety backup and the one-line rollback command — keep that output. And if you are locked out in a way none of these commands covers, support can see your licence and point you at the right recovery.