A command-line interface for interacting with JMAP servers, built on top of (our fork of) JMAP Dart client library. We use this tool, to test our fork of the client library. We mainly test against Stalwart. See jmap-dart-client/FORK#jmap-servers for other jmap servers we tested against.
For more information on JMAP, see also the JMAP Crash Course
- jmap-cli
- License
- Acknowledgement
- Before Running:
- Download flutter, see the flutter quickstart
- Note: We use flutter instead of pure dart as a dependency for integration tests.
- Execute
flutter pub getin the root directory of this repository to install dependencies.
- Download flutter, see the flutter quickstart
- Build the Executable:
dart compile exe bin/jmap_cli.dart -o bin/jmap_cliThis produces a self-contained executable which can be used on other machines (that don't have flutter or dart installed) as-is. Dart supports Linux/ Windows/ MacOS. The above command does not depend on your operating system.
- We support the jmap functions
/get/set, and/changesfor Contacts, AddressBooks, CalendarEvents, Calendars, Emails, Mailboxes, and FileNodes. - For Emails we additionally support
/queryfor filtering and paging,/importfor storing raw MIME messages, andEmailSubmission/setfor sending. - In the FileNode case we support (mostly) rsync-inspired file management operations.
The general command structure is
jmap_cli <objectType> <operation>, where ` is one of the following:
addressBookcontactcalendarcalendarEventemailfileNodesidentitymailboxsession
The available operations depend on the object type (and will be explained in their corresponding section), but common ones are
getgets all items ot the object typecreatecreates an itemdeletedeletes an itemchangesinformation on which items were created/ modified/ deleted since the given state-string
--urlURL of the JMAP server--userName,-uUsername used for authentication--userPassword,-pPassword for authentication--accountId,-aAccount id to operate on--id,-iUsed by delete commands--verbose,-vEnable detailed logging--versionPrint the CLI version--helpShow help
Credentials can also be provided via environment variables instead of flags. This avoids them being saved in shell history.
| Environment variable | Equivalent flag |
|---|---|
JMAP_URL |
--url |
JMAP_USERNAME |
--userName / -u |
JMAP_PASSWORD |
--userPassword / -p |
JMAP_ACCOUNT_ID |
--accountId / -a |
JMAP_TOKEN |
--token |
CLI flags take precedence if both are provided.
export JMAP_URL=http://localhost:8083/jmap/session
export JMAP_USERNAME=user@example.com
export JMAP_PASSWORD=secret
./bin/jmap_cli mailbox get --all
./bin/jmap_cli email get --alljmap_cli --helpjmap_cli <command> --helpRetrieve server capabilities and authentication info.
Usage:
jmap_cli session get --url <server-url> -u <user> -p <pass>Retrieve identity details for the current account.
Usage:
jmap_cli identity get --url <server-url> -u <user> -p <pass>Create AddressBook.
Options:
--name: Name of addressBook
Usage example:
jmap_cli addressBook create --url <server-url> -u <user> -p <pass> --name "My AddressBook"List AddressBooks.
Usage:
jmap_cli addressBook get --url <server-url> -u <user> -p <pass>Delete AddressBook by id.
Options:
--id: id of addressBook to delete
Usage example:
jmap_cli addressBook delete --url <server-url> -u <user> -p <pass> --id abcDetect AddressBook changes.
Options:
--state: If omitted, the CLI fetches the latest state
Usage example:
jmap_cli addressBook delete --url <server-url> -u <user> -p <pass> --state xyzFor historic reasons, we support not only the current ietf draft spec for contacts, but two other versions as well (which will get removed in the future). See jmap-dart-client/ContactAPIVersions.md for more details If you are interacting with a server that implements one of these legacy versions, you must set the corresponding flag.
--apiVersion <value>Supported values:
ietf(default)cyrusjscontact
Create a contact.
Options:
--file,-f: JSON file--fullNamefull name of Contact (supply either full name or json file)--addressBookIds,-b: Mandatory (except for legacy case where--apiVersion jscontact)--apiVersion:ietf(default),cyrus,jscontact
Usage example:
jmap_cli contact create --url <server-url> -u <user> -p <pass> --fullName "John Doe" --addressBookIds default --apiVersion ietfAlternative usage example with a JSON file:
jmap_cli contact create --url <server-url> -u <user> -p <pass> -f path/to/Contact.json --apiVersion jscontactDelete a contact.
Options:
--id: Id of Contact to delete
Usage example:
jmap_cli contact delete --url <server-url> -u <user> -p <pass> -i xyzFetch or list contacts.
Usage:
jmap_cli contact get --url <server-url> -u <user> -p <pass>Fetch Contact changes since previous state.
Options:
--state: If omitted, the CLI fetches the latest state automatically
Usage example:
jmap_cli contact changes --url <server-url> -u <user> -p <pass> --state abcCreate calendar.
Options:
--name: Name of calendar
Usage example:
jmap_cli calendar create --url <server-url> -u <user> -p <pass> --name "My Calendar"List calendars.
Usage:
jmap_cli calendar get --url <server-url> -u <user> -p <pass>Delete calendar by id.
Options:
--id: Id of calendar to delete
Usage example:
jmap_cli calendar delete --url <server-url> -u <user> -p <pass> -i xyzDetect calendar changes.
Options:
--state: If omitted, the CLI fetches the latest state
Usage example:
jmap_cli calendar changes --url <server-url> -u <user> -p <pass> -state abcCreate calendar events.
Options:
--file,-f: path to JSON file--title,-t: event title--calendarIds: calendar ids (mandatory)--start: ISO 8601 timestamp (optional)--duration: ISO 8601 duration (e.g.,PT1H)
Usage example:
jmap_cli calendarEvent create --url <server-url> -u <user> -p <pass> --title "event" --calendarIds defaultAlternative usage example with JSON file:
jmap_cli calendarEvent create --url <server-url> -u <user> -p <pass> -f path/to/calendarEvent.jsonList events.
Usage:
jmap_cli calendarEvent get --url <server-url> -u <user> -p <pass>Delete event by id.
Options:
--id: id of calendar event to delete
Usage example:
jmap_cli calendarEvent delete --url <server-url> -u <user> -p <pass> -i xyzDetect changes to calendarEvents.
Options:
--state: If omitted, the CLI fetches the latest state
Usage example:
jmap_cli calendarEvent changes --url <server-url> -u <user> -p <pass> -state abcFetch all emails or a single email by id. Use --all for full paged retrieval. Use -o out.eml to download raw MIME.
Options:
--id,-i: Id of email to fetch--all: Fetch all emails via paged queries--mailboxId,-m: Filter by mailbox id (required with--allon some servers)--batchSize: Number of emails per page when using--all(default: 50)--output,-o: Write output to a file. If the path ends in.eml, downloads raw MIME instead of JSON.
Usage examples:
jmap_cli email get --url <server-url> -u <user> -p <pass>
jmap_cli email get --url <server-url> -u <user> -p <pass> -i <emailId>
jmap_cli email get --url <server-url> -u <user> -p <pass> --all --mailboxId <mailboxId>
jmap_cli email get --url <server-url> -u <user> -p <pass> -i <emailId> -o out.emlCreate an email from CLI args or a file. .eml files are automatically imported via Email/import. JSON files use Email/set.
Options:
--file,-f: Path to a JSON or.emlfile--mailboxId,-m: Mailbox id to place the email in (required for.emlimport)--subject,-s: Email subject--from: Sender email address--to: Recipient email address--body,-b: Plain-text body
Usage examples:
jmap_cli email create --url <server-url> -u <user> -p <pass> --from sender@example.com --to recipient@example.com --subject "Hello" --body "Hi" --mailboxId <mailboxId>
jmap_cli email create --url <server-url> -u <user> -p <pass> -f email.json --mailboxId <mailboxId>
jmap_cli email create --url <server-url> -u <user> -p <pass> -f message.eml --mailboxId <mailboxId>Delete an email by id.
Options:
--id,-i: Id of email to delete
Usage example:
jmap_cli email delete --url <server-url> -u <user> -p <pass> -i <emailId>Create a draft and submit it for delivery in one step via Email/set + EmailSubmission/set.
Options:
--from: Sender email address--to: Recipient email address--subject,-s: Email subject--body,-b: Plain-text body--mailboxId,-m: Mailbox id for the draft--identityId: Identity id to send from (useidentity getto find it)
Usage example:
jmap_cli email send --url <server-url> -u <user> -p <pass> --from sender@example.com --to recipient@example.com --subject "Hello" --body "Hi" --mailboxId <mailboxId> --identityId <identityId>Query email ids with optional filtering and paging.
Options:
--mailboxId,-m: Filter to emails in this mailbox--limit,-l: Maximum number of ids to return--position: Zero-based index of the first result (for paging)
Usage examples:
jmap_cli email query --url <server-url> -u <user> -p <pass> --mailboxId <mailboxId>
jmap_cli email query --url <server-url> -u <user> -p <pass> --mailboxId <mailboxId> --limit 10 --position 0
jmap_cli email query --url <server-url> -u <user> -p <pass> --mailboxId <mailboxId> --limit 10 --position 10Fetch email changes since a given state.
Options:
--state: If omitted, the CLI fetches the latest state automatically
Usage example:
jmap_cli email changes --url <server-url> -u <user> -p <pass> --state <state>Fetch all mailboxes or a single mailbox by id. Use --all for full paged retrieval.
Options:
--id,-i: Id of mailbox to fetch--all: Fetch all mailboxes via paged queries
Usage examples:
jmap_cli mailbox get --url <server-url> -u <user> -p <pass>
jmap_cli mailbox get --url <server-url> -u <user> -p <pass> -i <mailboxId>
jmap_cli mailbox get --url <server-url> -u <user> -p <pass> --allCreate a mailbox.
Options:
--name,-n: Name of the mailbox--parentId: Id of the parent mailbox (for nested folders)
Usage examples:
jmap_cli mailbox create --url <server-url> -u <user> -p <pass> --name "My Folder"
jmap_cli mailbox create --url <server-url> -u <user> -p <pass> --name "Sub Folder" --parentId <parentId>Delete a mailbox by id.
Options:
--id,-i: Id of mailbox to delete
Usage example:
jmap_cli mailbox delete --url <server-url> -u <user> -p <pass> -i <mailboxId>Fetch mailbox changes since a given state.
Options:
--state: If omitted, the CLI fetches the latest state automatically
Usage example:
jmap_cli mailbox changes --url <server-url> -u <user> -p <pass> --state <state>Manage files and folders on the JMAP server.
List files and folders inside a directory (non-recursive).
Options:
--path: Path of folder to list (default:/)
Usage example:
jmap_cli fileNodes list --url <server-url> -u <user> -p <pass> --path someFolderShow files and folders recursively, analog to the Unix tree command.
Options:
--path: Root path to display (default:/)
Usage example:
jmap_cli fileNodes tree --url <server-url> -u <user> -p <pass> --path someFolderCreate a directory on the server.
Parameter:
<path>: Path of folder to create
Usage example:
jmap_cli fileNodes mkdir jmap:someFolder/NewFolder --url <server-url> -u <user> -p <pass>Delete a file or directory on the server.
Parameter:
<path>: Path of file or folder to delete
Options:
--recursive,-r: Delete folders and their contents
Usage example
jmap_cli fileNodes rm -r someFolder --url <server-url> -u <user> -p <pass>Copy files between the local filesystem and JMAP FileNodes.
Parameters:
<src> <dst> source and destination paths.
Use the jmap: prefix to indicate remote paths.
Exactly one of the source or destination must be a JMAP path.
Options:
--recursive,-r: In case of folders recurse and also copy contents
Usage examples:
Upload a local file to the server:
jmap_cli fileNodes cp upload.txt jmap:someFolder/local.txt --url <server-url> -u <user> -p <pass>Download a file from the server:
jmap_cli fileNodes cp jmap:someFolder/local.txt download.txt --url <server-url> -u <user> -p <pass>© audriga GmbH. source code is available under MIT license.
Thanks to all members of the IETF JMAP working group