Operator CLI
chatto operator provides local, root-equivalent account administration, channel room management, and attachment upload. Use it to create the first account on a server, recover access, or manage channels and files from a script.
The CLI talks to the running Chatto server over a Unix socket. It does not connect directly to NATS and does not use a Chatto login, bearer token, cookie, or RBAC role.
Enable the Operator API
Section titled “Enable the Operator API”The Operator API is disabled by default. Enable it in chatto.toml, then start or restart Chatto:
[operator_api]enabled = truesocket_path = "/tmp/chatto/operator.sock"The socket mode is always 0600. Its parent directory must be owned by the Chatto process user and must not be accessible to other users. Chatto refuses to start if these checks fail.
Import a portable archive
Section titled “Import a portable archive”The draft v1 importer accepts a directory in Chatto’s interchange format. It does not accept a Slack export directly.
chatto operator import ./archive --validate-only \ --channel-prefix old- --username-suffix -imported
chatto operator import ./archive --accept-omissions \ --channel-prefix old- --username-suffix -importedValidation checks local files and destination compatibility without server writes. The server must be running with the Operator API enabled. Both commands use the same naming options. Channel and username prefixes and suffixes are optional; defaults preserve source names. Invalid names and collisions stop validation.
The importer creates new channels; it does not merge existing channel history.
Keep imported channels unused until completion. To resume after a failure,
repeat the command with the same archive and options. The CLI saves a private
progress journal in your user cache directory. Use --progress PATH to select
another file. Preserve the journal for retries, including after completion.
Changed input cannot use the same journal. Do not reuse a journal with a
replacement server at the same socket path. The journal contains IDs and hashes,
not message bodies or copies of files. The CLI sends individual resource
requests to the Operator API; it does not send the archive as one request.
The importer supports public channels, human and bot accounts, known message
creation times, and available local files. New human accounts require usernames.
It preserves the deactivated status of new accounts. Deleted accounts remain
unsupported. Bots belong to the current active human server owner automatically.
If multiple owners exist, select one with --bot-owner USERNAME. You can also use
this option to select another active human. The journal saves the selected owner
ID for retries. Keep any override unchanged when you resume the import.
Imported bots receive no API keys or webhooks. Bots without a source username
receive a stable name that starts with bot-; supplied names remain unchanged.
User records can reference local avatar assets. The importer fills empty avatars
and preserves existing images, also for email-matched accounts. Images are limited
to 5 MiB and use normal avatar processing. The importer never fetches avatar URLs.
It preserves edits, threads, reactions, tombstone snapshots, and membership
history. Final membership does not create invented join notices. Shared source
files are uploaded separately for each message. Uploads use normal server media
processing and per-file policies. Unsupported record types fail validation;
server policy or media errors can still stop a partial import. No automatic
rollback occurs. There is no total archive size or record-count limit. The CLI
streams event bodies and file bytes, but keeps reference indexes in memory.
One JSON record is limited to 1 MiB. Normal upload expiry still applies.
The old archive RPC is removed. Update the CLI and server together. Local journals cannot resume imports that used the old server-side archive progress.
Email addresses match existing accounts after trimming whitespace and ignoring case. Matched accounts keep their usernames, profiles, credentials, and activation status; naming prefixes and suffixes apply only to new accounts. Source records sharing emails resolve to one account. For a new account, the first record supplies the profile. If emails point to different existing accounts, validation fails. Source records sharing emails must have the same kind and status. Bot accounts cannot have emails.
The importer trusts the archive’s email claims and adds unowned addresses as
verified emails. They can enable the configured email sign-in flow. It creates
no passwords. Accounts without emails need access configured separately.
The importer does not send historical notifications or fetch source
URLs. Files go to the configured attachment store, including S3 when enabled.
Declared losses require --accept-omissions. Generic export is not available yet.
Create a user
Section titled “Create a user”-
Create the account with a unique login:
Terminal window chatto operator user create \--login alice \--display-name "Alice" \--verified-email alice@example.comIn an interactive terminal, Chatto prompts for a password. Leave it empty to create a passwordless account. If you omit
--display-name, it defaults to the login. -
Copy the user ID from the output. Commands that change an existing account use this stable ID rather than its login or email address.
-
If the account should have an explicit role, assign one at creation time or afterwards:
Terminal window chatto operator user create \--login alice \--role admin \--role moderatorchatto operator user role add USER_ID admin
--verified-email adds the address as already verified; Chatto does not send a verification email. Only use it when you trust the address. --role accepts a configured role name and can be repeated.
Create a user non-interactively
Section titled “Create a user non-interactively”Read passwords from standard input or a restricted file for automation:
printf '%s\n' "$CHATTO_USER_PASSWORD" | \ chatto operator user create \ --login alice \ --display-name "Alice" \ --password-stdin
chatto operator user create \ --login alice \ --password-file /run/secrets/alice-passwordWhen the command is not attached to a terminal and you provide no password option, it creates a passwordless account. You can later add a password with user set-password.
Find and inspect users
Section titled “Find and inspect users”List users or inspect one account:
chatto operator user listchatto operator user list --search alicechatto operator user list --search alice@example.comchatto operator user get USER_IDchatto operator user get --login alicechatto operator user get --email alice@example.comUse user get --login or user get --email to find one account by its exact login or verified email address. A script can use either command to recover a user ID after an interrupted run. Supply exactly one selector: USER_ID, --login, or --email.
Search matches logins and display names, or an exact verified email address. list returns 20 users by default and supports offset pagination:
chatto operator user list --limit 100 --offset 0chatto operator user list --limit 100 --offset 100The maximum limit is 100. Human-readable output ends with total and has_more values so you can tell whether another page exists.
Find channel rooms
Section titled “Find channel rooms”List channel rooms, including archived rooms:
chatto operator room listchatto operator room list --name generalchatto operator room list --name general --json--name matches the exact stored channel name. If more than one room has that name, the command returns each room with its own ID. Results include the room ID, name, group ID, description, and archived state. Use the ID to identify a room in later commands.
The command returns 20 rooms by default. Use --limit and --offset to read more, up to 100 rooms per page:
chatto operator room list --limit 100 --offset 0chatto operator room list --limit 100 --offset 100Rooms appear in room ID order. Human-readable output ends with total and has_more. Pages are live reads, so room changes between requests can shift offsets. You can repeat the command safely.
Create a channel room
Section titled “Create a channel room”Create a channel in the first room group, or select a group by ID:
chatto operator room create --name "project-chat" --description "Project discussion"chatto operator room create --name "team-chat" --group-id GROUP_IDThe command returns the room ID, name, group ID, archived state, and description. Use --json when a script needs the full response. Chatto checks the name and description as it does for rooms created in the app.
An import script can save the returned Chatto room ID alongside its source room ID. If the response is lost, use room list --name to find the room before creating it again. A repeated create request with the same name returns a conflict.
Add a channel room member
Section titled “Add a channel room member”Add an existing user to a channel room by Chatto ID:
chatto operator room member add --room-id ROOM_ID --user-id USER_IDThe command returns both IDs. Use --json to get the member record. Repeating the command for a current member succeeds without adding a second membership. Chatto rejects missing users or rooms, DM rooms, archived rooms, universal rooms, and users with an active room suspension.
Upload a local attachment
Section titled “Upload a local attachment”Upload a file for an existing Chatto user and channel room:
chatto operator asset upload \ --room-id ROOM_ID \ --author-id USER_ID \ --file /path/to/exported-image.pngThe command prints the completed asset ID. Add --json to get an assetId field for a script. The file basename becomes the stored filename. Chatto infers the MIME type from that name. Use --filename NAME or --content-type TYPE to override either value. If you run the CLI inside Docker, --file must name a file inside that container.
The command reads only the local file. It does not fetch a URL from the export. Chatto applies its normal attachment size limits and media processing. It stores the bytes in its configured NATS or S3 asset backend. If you use S3, the storage provider receives the file bytes and the server’s IP address. The asset belongs to the selected author; the upload action is recorded as a system action. The author does not need a session or file-attachment permission for this operator command. The room must be an active channel.
If an upload command returns an error, it attempts to cancel the incomplete upload. If the process stops or cannot reach the server, server cleanup removes abandoned chunks after expiry. A completed asset remains pending until a message attaches it; Chatto removes an unattached pending asset after 24 hours. Running the command again can create a different asset ID, so an import script should save each returned ID. The CLI reports only an asset ID; a later message command attaches it.
Import a historical message
Section titled “Import a historical message”Import one message for an existing Chatto user and channel room:
chatto operator message import \ --room-id ROOM_ID --author-id USER_ID \ --created-at 2022-08-18T11:11:11.147Z \ --body-file /path/to/exported-message.txtThe command prints the new Chatto message ID. Use --json to read messageId in a script. Supply text with --body, --body-file, or --body-stdin. Use only one of these flags. A message can omit text when it has at least one --attachment-asset-id ASSET_ID flag. Repeat that flag for more attachments.
Use --edited-at RFC3339 to preserve the last edit time. Use --in-reply-to CHATTO_MESSAGE_ID to refer to an existing message in the same room. A reply reference does not create a Chatto thread. To preserve an exported preview, use --preview-url URL with optional --preview-title, --preview-description, and --preview-type fields. The URL must use HTTP or HTTPS. Chatto stores these values without fetching the URL.
The room must be an active channel, and the author must exist. Attached assets must belong to that author and room. Chatto encrypts the body and applies its normal message and attachment limits. Historical imports do not notify users, mark messages unread, follow threads, or send bot webhooks. The command does not require a user session or room membership.
For safe retries, supply --idempotency-key UUID and retain the same UUID and arguments for that message. Exact retries return the original message ID for 30 minutes after the server first accepts the key. Changed arguments conflict, and retries do not extend the window. A completed retry returns the original ID even after the message is retracted or its channel archived. Without a key, each successful call creates a new message.
Use --deleted to import an already deleted message as a native tombstone. Omit body, attachments, preview, and edit time. The original creation time and author remain; Chatto records the retraction at import time because the source deletion time is unknown. You can combine --deleted with --create-thread or --thread-id. Historical replies can target a deleted root. Upgrade all server replicas before using deleted imports.
Tombstone retractions use ordinary live delivery and reconnect replay. Connected clients can receive deletion updates during import.
Save the UUID and first-attempt time before sending, and save the returned message ID. Stop retries before 30 minutes; after expiry the same UUID can create another message. Reconcile an older uncertain result manually. Finish upgrading all replicas to support import keys before relying on this guarantee: older servers can ignore the field.
To establish an empty thread on a new root, add --create-thread. To import a reply inside a thread, use the existing root’s ID:
chatto operator message import \ --room-id ROOM_ID --author-id USER_ID \ --created-at 2022-08-19T11:11:11.147Z \ --thread-id ROOT_MESSAGE_ID \ --body-file /path/to/exported-reply.txtThe thread ID is its root message ID. The reply establishes the thread if necessary. Do not combine --create-thread with --thread-id. The root must be a message in the same room, not another reply or a channel echo. Imported placement is independent of the room’s interactive threading mode. A thread reply does not also appear in the channel timeline. --in-reply-to remains a separate reply reference and does not select a thread.
Import a historical reaction
Section titled “Import a historical reaction”chatto operator message import-reaction \ --room-id ROOM_ID --message-event-id MESSAGE_ID \ --user-id USER_ID --emoji heart --jsonThe user and message must exist in the specified active channel. The user does not need room membership. Use a reaction name without surrounding colons, such as heart or party_parrot. Plain names contain 1–128 ASCII letters, digits, underscores, plus signs, or hyphens. Known emoji also accept valid skin-tone suffixes, such as thumbsup::skin-tone-4, within the same length limit. Names are case-sensitive and remain unchanged. Unknown plain names are accepted; clients can show them as :name:. A channel echo ID resolves to its original thread reply.
Historical reactions can also target deleted messages. They remain visible on the native tombstone. Upgrade all replicas before importing reactions on deleted messages.
The response has added: true for a new reaction. For an existing reaction, added is false (the JSON field can be omitted). Repeating the same user/message/emoji is safe, including after a lost response. Imports bypass the interactive per-user reaction-count limit and do not create notifications, unread activity, or live reaction frames. The mapped user can remove the reaction normally when they have access.
No source reaction timestamp is required. The event records the import time. Before the first reaction import, finish updating all replicas to a version that supports this command. Earlier binaries cannot preserve the mapped reactor or suppress historical reaction activity; do not serve this imported state with an earlier binary.
Update a user
Section titled “Update a user”Change a login, a display name, or both:
chatto operator user update USER_ID --new-login alice-renamedchatto operator user update USER_ID --display-name "Alice Example"chatto operator user update USER_ID \ --new-login alice-renamed \ --display-name "Alice Example"Add an email address that Chatto should treat as already verified:
chatto operator user add-email USER_ID --email alice@example.comThe operator CLI can add a verified email address, but it cannot remove one.
Set a password
Section titled “Set a password”Run the command without a password option to enter the new password at an interactive prompt:
chatto operator user set-password USER_IDFor automation, use standard input or a restricted file:
printf '%s\n' "$CHATTO_USER_PASSWORD" | \ chatto operator user set-password USER_ID --password-stdin
chatto operator user set-password USER_ID \ --password-file /run/secrets/alice-passwordThe new password cannot be empty. Setting a password does not require the previous password.
Manage external sign-in identities
Section titled “Manage external sign-in identities”List the stored identities for an existing human account:
chatto operator user identity list USER_IDchatto operator user identity list USER_ID --jsonEach row shows the identity hash, provider, issuer, subject, and
login_available. Stale links remain in the list. login_available means that
a configured provider accepts the stored identity namespace. It does not test
provider reachability or the status of the provider account. Historical links
can have an empty issuer or subject; Chatto cannot determine availability for
a hash-only link.
Verify that the provider subject belongs to this user, then link it:
chatto operator user identity link USER_ID \ --provider company-sso \ --subject 'provider-subject'Use the provider ID from [[auth.providers]]. Chatto uses that provider’s
current issuer and type. The subject must be exact; do not use an email address
to infer account ownership. The command does not contact the provider or
perform an SSO login. It refuses an identity owned by another account.
A repeat for the same user and identity succeeds without another write.
Remove a link with the hash returned by identity list:
chatto operator user identity unlink USER_ID SUBJECT_HASHAnother configured identity or an enabled password sign-in method must remain.
A stored password does not count when auth.direct_login = false. Existing
sessions stay valid. A missing link returns an error; use identity list to
check the result after an interrupted command.
Recover access after an OIDC issuer change
Section titled “Recover access after an OIDC issuer change”Keep the original Chatto account. Update the configured provider’s issuer_url
to match the provider, then restart Chatto. Verify the current subject for that
person at the provider; an issuer change does not guarantee an unchanged subject.
- Use
identity listto find the old link and save its hash. - Use
identity linkwith the configured provider and the verified subject. - Ask the user to sign in through SSO and check that the original account opens.
- Use
identity unlinkto remove the old hash.
Password login can remain disabled throughout recovery. Account IDs, roles, and messages stay unchanged. These commands record new identity changes and preserve the account’s history.
Clear a username-change cooldown
Section titled “Clear a username-change cooldown”Allow a user or bot to change its username again after a recent username change:
chatto operator user clear-username-cooldown USER_IDThe command does not change the user’s current username. It clears the 30-day wait before the next username change. Use --json to get a cleared result for a script.
Manage roles
Section titled “Manage roles”Assign or revoke a configured server role by name:
chatto operator user role add USER_ID moderatorchatto operator user role remove USER_ID moderatorUse user list --json or user get USER_ID --json to inspect the roles currently assigned to an account. Role changes take effect through the running server’s normal domain services.
Delete a user
Section titled “Delete a user”chatto operator user delete USER_IDIn an interactive terminal, Chatto asks you to type a confirmation containing the user ID. Non-interactive scripts must explicitly confirm deletion:
chatto operator user delete USER_ID --yesRun commands in Docker Compose
Section titled “Run commands in Docker Compose”Run the CLI inside the app container as the same chatto OS user that owns the socket:
docker compose exec -u chatto chatto /chatto operator user list
docker compose exec -u chatto chatto /chatto operator user create \ --login alice \ --display-name "Alice"For password input from your terminal, keep the default pseudo-terminal allocated by docker compose exec. For scripted input, use --password-stdin:
printf '%s\n' "$CHATTO_USER_PASSWORD" | \ docker compose exec -T -u chatto chatto \ /chatto operator user create --login alice --password-stdinGlobal options and JSON output
Section titled “Global options and JSON output”The following options apply to every chatto operator subcommand:
| Option | Purpose |
|---|---|
-c, --config PATH | Read configuration from PATH instead of chatto.toml. |
--operator-socket PATH | Connect to a specific Operator API socket. |
--json | Print the protobuf response as JSON for scripts. |
The socket path is resolved in this order:
--operator-socketCHATTO_OPERATOR_API_SOCKET_PATHoperator_api.socket_pathin the selected configuration file/tmp/chatto/operator.sock
For example:
chatto operator user list --jsonchatto operator user get USER_ID --jsonchatto operator --operator-socket /run/chatto/operator.sock user listchatto operator --config /etc/chatto/chatto.toml user listTroubleshooting
Section titled “Troubleshooting”If a command cannot connect to the socket, check that:
- the running server has
operator_api.enabled = true; - the CLI and server resolve the same socket path;
- you run the CLI as the OS user that owns the socket;
- the Chatto server is running; and
- in containers, you execute the command in the container that owns the socket rather than on the host.
Use chatto operator --help, chatto operator user --help, or a command’s --help output for the exact options supported by your installed Chatto version.