Skip to content
Chatto v0.5.0

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.

The Operator API is disabled by default. Enable it in chatto.toml, then start or restart Chatto:

[operator_api]
enabled = true
socket_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.

The draft v1 importer accepts a directory in Chatto’s interchange format. It does not accept a Slack export directly.

Terminal window
chatto operator import ./archive --validate-only \
--channel-prefix old- --username-suffix -imported
chatto operator import ./archive --accept-omissions \
--channel-prefix old- --username-suffix -imported

Validation 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.

  1. Create the account with a unique login:

    Terminal window
    chatto operator user create \
    --login alice \
    --display-name "Alice" \
    --verified-email alice@example.com

    In 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.

  2. Copy the user ID from the output. Commands that change an existing account use this stable ID rather than its login or email address.

  3. 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 moderator
    chatto 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.

Read passwords from standard input or a restricted file for automation:

Terminal window
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-password

When 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.

List users or inspect one account:

Terminal window
chatto operator user list
chatto operator user list --search alice
chatto operator user list --search alice@example.com
chatto operator user get USER_ID
chatto operator user get --login alice
chatto operator user get --email alice@example.com

Use 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:

Terminal window
chatto operator user list --limit 100 --offset 0
chatto operator user list --limit 100 --offset 100

The maximum limit is 100. Human-readable output ends with total and has_more values so you can tell whether another page exists.

List channel rooms, including archived rooms:

Terminal window
chatto operator room list
chatto operator room list --name general
chatto 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:

Terminal window
chatto operator room list --limit 100 --offset 0
chatto operator room list --limit 100 --offset 100

Rooms 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 in the first room group, or select a group by ID:

Terminal window
chatto operator room create --name "project-chat" --description "Project discussion"
chatto operator room create --name "team-chat" --group-id GROUP_ID

The 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 an existing user to a channel room by Chatto ID:

Terminal window
chatto operator room member add --room-id ROOM_ID --user-id USER_ID

The 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 file for an existing Chatto user and channel room:

Terminal window
chatto operator asset upload \
--room-id ROOM_ID \
--author-id USER_ID \
--file /path/to/exported-image.png

The 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 one message for an existing Chatto user and channel room:

Terminal window
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.txt

The 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:

Terminal window
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.txt

The 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.

Terminal window
chatto operator message import-reaction \
--room-id ROOM_ID --message-event-id MESSAGE_ID \
--user-id USER_ID --emoji heart --json

The 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.

Change a login, a display name, or both:

Terminal window
chatto operator user update USER_ID --new-login alice-renamed
chatto 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:

Terminal window
chatto operator user add-email USER_ID --email alice@example.com

The operator CLI can add a verified email address, but it cannot remove one.

Run the command without a password option to enter the new password at an interactive prompt:

Terminal window
chatto operator user set-password USER_ID

For automation, use standard input or a restricted file:

Terminal window
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-password

The new password cannot be empty. Setting a password does not require the previous password.

List the stored identities for an existing human account:

Terminal window
chatto operator user identity list USER_ID
chatto operator user identity list USER_ID --json

Each 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:

Terminal window
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:

Terminal window
chatto operator user identity unlink USER_ID SUBJECT_HASH

Another 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.

  1. Use identity list to find the old link and save its hash.
  2. Use identity link with the configured provider and the verified subject.
  3. Ask the user to sign in through SSO and check that the original account opens.
  4. Use identity unlink to 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.

Allow a user or bot to change its username again after a recent username change:

Terminal window
chatto operator user clear-username-cooldown USER_ID

The 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.

Assign or revoke a configured server role by name:

Terminal window
chatto operator user role add USER_ID moderator
chatto operator user role remove USER_ID moderator

Use 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.

Terminal window
chatto operator user delete USER_ID

In an interactive terminal, Chatto asks you to type a confirmation containing the user ID. Non-interactive scripts must explicitly confirm deletion:

Terminal window
chatto operator user delete USER_ID --yes

Run the CLI inside the app container as the same chatto OS user that owns the socket:

Terminal window
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:

Terminal window
printf '%s\n' "$CHATTO_USER_PASSWORD" | \
docker compose exec -T -u chatto chatto \
/chatto operator user create --login alice --password-stdin

The following options apply to every chatto operator subcommand:

OptionPurpose
-c, --config PATHRead configuration from PATH instead of chatto.toml.
--operator-socket PATHConnect to a specific Operator API socket.
--jsonPrint the protobuf response as JSON for scripts.

The socket path is resolved in this order:

  1. --operator-socket
  2. CHATTO_OPERATOR_API_SOCKET_PATH
  3. operator_api.socket_path in the selected configuration file
  4. /tmp/chatto/operator.sock

For example:

Terminal window
chatto operator user list --json
chatto operator user get USER_ID --json
chatto operator --operator-socket /run/chatto/operator.sock user list
chatto operator --config /etc/chatto/chatto.toml user list

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.