Use the CLI

This page explains how to call sofatofu operations through the sofatofu CLI. To install the CLI, sign in, update or uninstall, see Setup and sign-in.

Command form

The input keys of an operation become arguments:

• id and ids go after the verb, separated by spaces. They are not flags.
• Every other key is a flag with the key name in kebab case: read_id is --read-id, record_ids is --record-ids, and order_by is --order-by.
• Text and numbers follow the flag, such as --type company or --limit 200. Quote text that holds spaces.
• true is the flag alone, such as --count. Leave a flag out for false.
• A list of IDs, such as record_ids, repeats the flag once for each item.
• An object or a list of objects, such as filter, patch and records, takes one JSON value. Write it inline in single quotes, put @ before a file path to read the value from that file, or use @- to read it from stdin. If the value holds a single quote, or you run in PowerShell, use @<path> or @-. A file is useful when a script builds the value, such as an import batch.
• read_id goes in as --read-id="<read_id>". Use the equals sign so an ID that starts with - isn't parsed as a flag.

For example, this call:

record update {"type":"deal","ids":["k7m2p9qx4dz1","b3n8r2wq7yt5"],"patch":{"stage":"won"},"reason":"Contracts signed","read_id":"<read_id>"}

is this command:

sofatofu record update k7m2p9qx4dz1 b3n8r2wq7yt5 --type deal --patch '{"stage":"won"}' --reason "Contracts signed" --read-id="<read_id>"

These commands show a repeated flag and a value read from a file:

sofatofu change reverse m5n1p8q2r7s4 --record-ids c4d8e2f6g0h3 --record-ids d5e9f3g7h1j4 --reason "Restore the contacts removed by mistake" --read-id="<read_id>"
sofatofu record create --type company --records @batch-03.json --reason "Import companies, batch 3 of 12" --read-id="<read_id>"

Help

Run sofatofu --help to list the commands, and sofatofu <noun> <verb> --help to see the flags of one command. The help of a command also states its effect: whether it only reads, adds data, can change or delete data, or sends data to a recipient you name.

Results and exit codes

A command that succeeds prints its JSON result on stdout and exits with code 0. A command that fails prints the JSON error body on stderr. Its exit code depends on the error:

Exit code	Error
2	invalid_input
3	not_signed_in
4	No answer or server failure: connection_failed, internal, server_busy, unexpected_response, login_unavailable, account_unavailable, update_unavailable
1	Every other error

For not_signed_in, sign in as Setup and sign-in describes.

Warnings and notices

A command can print a line that starts with warning: or notice: on stderr, after its result. These lines don't change the result or the exit code.

• A skill version warning: follow it once. Carry on with the user's task even if the warning stays. Whether the task succeeds or fails, mention the warning in your final response and ask the user to start a new agent session.
• A newer release notice: tell the user they can install it with sofatofu update.