ducko-cli

Files (3)

• SKILL.md
• stub-server-smoke-testing.md · references/
• tcp-relay.py · scripts/

SKILL.md (first lines)

# Ducko CLI

## Quick Start

```
ducko <subcommand> [options]
ducko --help
```

Default subcommand is `interactive` (REPL mode).

## Authentication

Password lookup order: macOS Keychain first, then prompt on `/dev/tty` if stdin is a TTY. Accounts can be created with `ducko account add <jid>` or in DuckoApp — the CLI and GUI share the same SwiftData database and Keychain.

## Global Options

| Option | Description |
|---|---|
| `--output plain\|ansi\|json` | Output format. Defaults to ANSI in terminal, plain when piped. |
| `--account <uuid>` | Select account by UUID. Uses first account if omitted. |

Each subcommand declares these options itself. Some reject them with "Unknown option", including `account add` and `account delete`. Pass them after the full subcommand path (e.g. `roster list --output json`).

## Subcommands

Unless noted otherwise, each subcommand connects, performs its action, and disconnects.

### `send [--file <path>] [--method auto|http|jingle] <jid> [body]`

Send a message or file, then disconnect. At least one of `--file` or `body` is required. When both are provided, the file is uploaded first, then the body is sent as a separate caption message.

`--method auto` (the default) and `http` upload the file over XEP-0363. `jingle` sends it peer-to-peer over XEP-0234 and returns only once the contact has accepted and received it, or the transfer has failed. With a full JID, `jingle` sends to that session. With a bare JID it picks one of the contact's online sessions that takes direct transfers. That needs the contact's presence to have arrived, so in this connect-send-disconnect command a full JID is the reliable form. A direct send appears in the chat's history as a sent file, marked `[delivered]` once it arrives or `[error: <reason>]` when it fails.

```
ducko send alice@example.com "Hello"
ducko send --file photo.jpg alice@example.com
ducko send --file photo.jpg alice@example.com "Check this out"
ducko send --file photo.jpg --method jingle alice@example.com/resource
```

### `interactive` (default)

REPL mode. Connects once, then accepts commands on stdin:

- `send <jid> <message>` — send a message (auto-detects rooms)
- `/roster` — show contacts grouped with presence indicators
- `/status [status] [message]` — get or set presence status
- `/who` — show online contacts only
- `/history <jid> [limit]` — show message history (default 20 messages)
- `/join <room> [nickname]` — join a MUC room (sets as current room)
- `/leave [room]` — leave a MUC room (uses current room if omitted)
- `/members [room]` — show room occupants
- `/pm <nickname> <message>` — send private message to a room occupant (current room)
- `/topic [room] [text]` — view or set room topic
- `/nick <nickname>` — change nickname in current room
- `/destroy [reason]` — destroy current room (owner only)
- `/voice grant|revoke <nickname>` — grant or revoke voice (moderator only)
- `/affiliations [member|admin|owner|outcast]` — list affiliations (default: member)
- `/config [submit-default]` — show the room configuration form, or submit the defaults to unlock a new room. The form shows its title, instructions and fixed text, and each field with its description and a `(required)` marker, with text-private values as `********`. In JSON it is one `data_form` record with `title`, `instructions` and a `fields` array, which `/check-registration` nests under `form`
- `/rooms [service]` — discover available rooms on MUC service
- `/sendfile [jid] <path>` — send a file (uses current room if jid omitted)
- `/senddirect <jid> <path>` — send a file straight to one of the contact's online devices (XEP-0234) instead of uploading it. The contact's devices are asked first. The command prints an error when the file is missing or is a folder, or when no device takes direct transfers. Otherwise it prints `Sending <file> to <jid> directly. Use /transfers to check progress.` and the prompt returns. A decline, or a transfer that fails once under way, is printed when it happens. A failure before that point, such as the device refusing the offer or the file's contents not being readable, prints nothing and shows only in `/transfers` and the history.
- `/accept [id]` — accept an incoming file offer (Jingle or link) and save it to `~/Downloads`. The id is the one printed in the `[File offer]` line. Without an id, it takes this account's newest offer.
- `/decline [id]` — decline an incoming file offer. Without an id, it takes this account's newest offer.
- `/transfers` — list active file transfers with progress
- `/add <jid> [name]` — add contact to roster
- `/remove <jid>` — remove contact from roster
- `/approve <jid>` — approve subscription request
- `/deny <jid>` — deny subscription request
- `/block <jid>` — block an address, as `blocklist add` does
- `/unblock <jid>` — unblock exactly that entry, as `blocklist remove` does
- `/blocklist` — fetch and show the block list, as `blocklist list` does
- `/avatar [jid]` — view avatar info (own if no JID, contact's if given)
- `/profile` — view own vCard profile
- `/connection-info` — show TLS connection info (protocol, cipher, certificate)
- `/encrypt <jid> on|off` — toggle OMEMO encryption for a conversation. `off` also keeps a contact's encrypted message from switching it back on.
- `/pref chatstates on|off` — toggle chat state notifications (typing indicators)
- `/pref markers on|off` — toggle displayed markers (read receipts)
- `/reply <jid> <message>` — reply to the last incoming message from JID, or in the room JID, skipping a room message the room gave no id of its own. The reply starts with a quote of that message, unless the message was encrypted and the reply is not.
- `/retract <jid>` — retract last sent message to JID (a room message only once the room has echoed it)
- `/edit <jid> <new-body>` — edit last sent message to JID
- In `/reply`, `/retract` and `/edit`, `room@service/nick` names the private chat with that occupant. An address that names none of the account's chats, such as a contact's full JID, is reported as an error.
- `/moderate [reason]` — moderate last message in current room (MUC moderator)
- `/search <jid> <query>` — search the whole message history with JID. Prints the newest 20 matches, oldest first.
- `/searchall <query>` — search all the account's conversations, as `history --search <query>` does. Prints the newest 20 matches.
- `/directed-presence <jid>` — send directed presence to a JID
- `/check-registration [jid]` — show server registration form
- `/submit-registration [jid]` — submit registration to server/component. It prompts for every field the form asks for: a legacy form's elements, such as username, password, nick, name and email, all of them required, or a data form's fields. Enter keeps the current value. A required field asks again until it has one, and input that ends before then submits nothing. A form that only names a web page is printed and not submitted. The legacy password and a text-private field read hidden input of at most 4094 bytes from the terminal. Without a terminal, a text-private field keeps its value, and a required one that has none ends with `No <field> provided…`. A boolean field takes yes or no (also y/n, on/off, true/false, 1/0) and asks again on any other answer. A list field takes only a listed option's value or label, comma-separated for list-multi. Text-multi and jid-multi read lines up to an empty one, and jid-multi also splits on commas.
- `/unregister-account` — unregister account from server
- `help` — show available commands
- `quit` / `exit` — disconnect and exit

Interactive mode also prints async events as they arrive: typing indicators, delivery receipts, read markers, message corrections, Jingle transfer state changes, and MUC lifecycle events (`[new room]`, nickname changes, room destruction). Terminal bell rings on incoming messages and file transfer offers.

```
ducko interactive
```

### `history [<jid>]`

View message history from the local database. With `--server`, connects to fetch from the XMPP server. The JID can be left out only together with `--search`.

| Option | Description |
|---|---|
| `--limit <n>` | Maximum number of messages (default: 20) |
| `--before <date>` | Show messages before this ISO 8601 date (pagination). Does not work with `--search`. |
| `--search <query>` | Show the newest messages that contain the keyword |
| `--server` | Fetch from server when local history is empty (requires connection). Does not work with `--search`. |

```
ducko history alice@example.com
ducko history alice@example.com --limit 5
ducko history alice@example.com --before 2026-03-01T00:00:00Z
ducko history alice@example.com --output json --limit 10
ducko history alice@example.com --server
ducko history alice@example.com --search invoice
ducko history --search invoice --limit 50
```

From ducko-im/ducko, GPL-3.0.

More from ducko-im/ducko