zulip/docs/production/management-commands.md

# Management commands

Sometimes, you need to modify or inspect Zulip data from the command
line.  To help with this, Zulip ships with over 100 command-line tools
implemented using the [Django management commands
framework][django-management].

[django-management]: https://docs.djangoproject.com/en/2.2/ref/django-admin/#django-admin-and-manage-py

## Running management commands

Start by logging in as the `zulip` user on the Zulip server.  Then run
them as follows:

```
cd /home/zulip/deployments/current

# Start by reading the help
./manage.py <command_name> --help

# Once you've determine this is the command for you, run it!
./manage.py <command_name> <args>
```

A full list of commands is available via `./manage.py help`; you'll
primarily want to use those in the `[zerver]` section as those are the
ones specifically built for Zulip.

As a warning, some of them are designed for specific use cases and may
cause problems if run in other situations.  If you're not sure, it's
worth reading the documentation (or the code, usually available at
`zerver/management/commands/`; they're generally very simple programs).

### Accessing an organization's `string_id`

Since Zulip supports hosting multiple organizations on a single
server, many management commands require you specify which
organization ("realm") you'd like to modify, either via numerical or
string ID (usually the subdomain).

You can see all the organizations on your Zulip server using
`./manage.py list_realms`.

```
zulip@zulip:~$ /home/zulip/deployments/current/manage.py list_realms
id    string_id                                name
--    ---------                                ----
1     zulipinternal                            None
2                                              Zulip Community
```

(Note that every Zulip server has a special `zulipinternal` realm
containing system-internal bots like `Notification Bot`; you are
unlikely to ever need to interact with that realm.)

Unless you are
[hosting multiple organizations on your Zulip server](../production/multiple-organizations.md),
your single Zulip organization on the root domain will have the empty
string (`''`) as its `string_id`.  So you can run e.g.:

```
zulip@zulip:~$ /home/zulip/deployments/current/manage.py show_admins -r ''
```

Otherwise, the `string_id` will correspond to the organization's
subdomain.  E.g. on `it.zulip.example.com`, use
`/home/zulip/deployments/current/manage.py show_admins -r it`.

## manage.py shell

If you need to query or edit data directly in the Zulip database, the
best way to do this is with Django's built-in management shell.

You can get an IPython shell with full access to code within the Zulip
project using `manage.py shell`, e.g., you can do the following to
change a user's email address:

```
$ cd /home/zulip/deployments/current/
$ ./manage.py shell
In [1]: user_profile = get_user_profile_by_email("email@example.com")
In [2]: do_change_user_delivery_email(user_profile, "new_email@example.com")
```

Any Django tutorial can give you helpful advice on querying and
formatting data from Zulip's tables for inspection.

We recommend against directly editing objects and saving them using
Django's `object.save()`.  While this will save your changes to the
database, for most objects, in addition to saving the changes to the
database, one may also need to flush caches, notify the apps and open
browser windows, and record the change in Zulip's `RealmAuditLog`
audit history table.  For almost any data change you want to do, there
is already a function in `zerver.lib.actions.py` with a name like
`do_change_full_name` that updates that field and notifies clients
correctly.

For convenience, Zulip automatically import `zerver/models.py` and
`zerver/lib/actions.py` into every management shell; if you need to
access other functions, you'll need to import them yourself.

## Other useful manage.py commands

There are dozens of useful management commands under
`zerver/management/commands/`.  We detail a few here:

* `./manage.py help`: Lists all available management commands.
* `./manage.py dbshell`: If you're more comfortable with raw SQL than
  Python, this will open a Postgres SQL shell connected to the Zulip
  server's database.  Beware of changing data; editing data directly
  with SQL will often not behave correctly because Postgres doesn't
  know to flush Zulip's caches or notify browsers of changes.
* `./manage.py send_custom_email`: Can be used to send an email to a set
  of users.  The `--help` documents how to run it from a `manage.py
  shell` for use with more complex programmatically computed sets of
  users.
* `./manage.py send_password_reset_email`: Sends password reset email(s)
  to one or more users.
* `./manage.py change_user_email`: Change a user's email address.
* `./manage.py knight`: Can toggle whether a user is an administrator
  (easier done [via the
  UI](https://zulip.com/help/change-a-users-role)) or create an
  API super user bot (with `--permission=api_super_user`), which are
  needed for some content mirroring integrations.
* `./manage.py export_single_user` does a limited version of the [main
  export tools](../production/export-and-import.md) containing just
  the messages accessible by a single user.

All of our management commands have internal documentation available
via `manage.py command_name --help`.