CLI commands ​

Run socli <command> [arguments] [options] from your shell to read feeds, publish posts or manage accounts. Options that take a value use --option value, such as --net bluesky or --count 10. The image option uses an equals sign: --images=blocks.

socli feed saved --net bluesky --json
socli search "rust tui" --net bluesky --print --no-prompt
socli post "hello from the terminal" --net x,bluesky

Read commands open the full-screen TUI when both input and output are terminals. Add --json to get one JSON value and exit, or --print --no-prompt to print terminal text and exit. With redirected input or output, reads print once without opening the TUI. Writes with supplied text and account/configuration commands return after the operation; sign-in can still require a browser or a prompt.

To try a read and a write check without an account:

socli feed --demo --json
socli post "hello from the terminal" --demo --net x,bluesky --dry-run --json

Output modes ​

Coding agents get JSON by default and never open prompts. --print selects text output for them; --json takes precedence when both are present. Agents documents detection, JSON fields and errors.

Networks and targets ​

--net accepts x, bluesky, devnull, threads, mastodon, a comma-separated list or all. Aliases are twitter, bsky, dev/null, dev-null and masto. Global options can appear before or after a command.

For reads, scope comes from --net, then SOCLI_NET, then feed.networks in the configuration, then the available signed-in networks. Public search, profile and thread reads can use an explicitly named network without a session where its API allows it; Networks lists the restrictions.

For post, --net or SOCLI_NET chooses the destinations. Without either, SoCLI uses the default set by socli auth default, or the only signed-in network that can post. With several possible destinations and no default, the command asks you to specify --net. --net all posts to every signed-in network that can publish. The reader's feed.networks filter does not choose posting destinations.

A post target is the id from a JSON read, in the form <network>:<native-id>. Supported post URLs from X, Bluesky, dev/null and Mastodon also work. Threads requires the JSON id because its API cannot resolve post URLs. For a bare native id, specify one network with --net, or configure a default. view requires a scoped id or post URL when targeting a post.

In the examples below, set $post_id to an actual post's JSON id and $handle to the account handle you want to read or follow.

Read ​

socli feed following --net bluesky --count 10 --json
socli user "$handle" --net mastodon --print --no-prompt
socli thread "$post_id" --json
socli notifications --net bluesky --json
socli bookmarks --json

--count defaults to 15 posts requested per network. Networks can enforce their own page size. The reader asks each signed-in network for at least 20, and starts the next page when the selection reaches the 10th post of the current page; m loads one page the same way. A shell read prints the current page. socli ask is interactive: text passed after it is currently ignored, and --json or --print returns the feed rather than an answer.

Write ​

socli post "hello from the terminal" --net bluesky --dry-run --json
socli reply "$post_id" "agreed"
socli quote "$post_id" "worth reading" --net x,bluesky
socli like "$post_id"
socli follow "$handle" --net bluesky

--dry-run checks sign-in, supported actions and text length for writes without sending them. --json reports each destination separately, including errors, and a failed destination makes the command exit with code 1. Networks lists which actions each network supports.

Text, stdin and the composer ​

Pass text as a quoted argument or use - to read standard input. Outside agent mode, omitting text also reads redirected input. At a terminal, omitting text opens the composer for post, reply or quote.

printf '%s\n' 'hello from a pipe' | socli post - --net bluesky
socli post - --net bluesky < post.txt
socli post --net bluesky

Posts contain text only; there is no attachment option. <b>, <strong>, <i> and <em> become Unicode bold and italic letters before sending. These letters affect accessibility and character limits; add --raw to preserve the text as typed. --raw belongs to post, reply and quote, so place it after one of those command names.

For text that starts with a dash, place -- before the text so the shell command treats it as an argument rather than an option.

Links and images ​

socli share "$post_id" --profile --json
socli view demo
socli view "$post_id" --json

Images covers graphics modes and terminal support.

Accounts and sign-in ​

Login options ​

The Sign in page explains prerequisites, prompts, environment variables and browser flows.

Advanced authentication ​

socli auth <network> login accepts the same options as socli login <network>, and socli auth <network> logout signs that network out. The other authentication commands are:

Configuration and drafts ​

socli config get ui.detail
socli config set ui.theme nord
socli config set feed.networks x,bluesky
socli drafts --json

Configuration lists valid keys and values. Resume a draft with ctrl-o in the composer; the CLI has no draft-send or draft-resume subcommand.

Global flags ​

These options are accepted before or after the command. They apply to the relevant read, rendering or write operation; they do not turn account/configuration commands into demo operations.

--raw, share --profile, delete --yes and the login/authentication options are command-specific, as listed in their sections above.

Help and completions ​

socli help
socli help post
socli post --help
socli help --json
socli completions zsh

socli --version (or socli -V) prints the installed version. socli help lists the CLI, socli help <command> shows usage and examples, and socli help --json returns the command table. socli completions <shell> prints a completion script for bash, zsh, fish, elvish or powershell; Install shows how to save it.

In-reader commands ​

The TUI command palette (: or ctrl-k) and the scrollback SoCLI> prompt share an interactive grammar. Enter commands without the socli prefix. Use net bluesky to change scope, following to pick a feed and post numbers or the selection for actions. Shell options such as --net, --json and --raw are not parsed here, and quotes are treated as text rather than shell delimiters.

net bluesky
following
search rust tui
reply 2 agreed

Interactive post numbers start at 1. They are positions in the current list, not the scoped ids used by the shell CLI. help in the TUI opens the key reference; help in the scrollback prompt lists interactive commands. The scrollback prompt requires theme <name> and applies it only to the running session. In the TUI, :theme <name> also saves the choice. Keys covers the keyboard controls.

Exit codes ​

JSON errors normally go to stderr as one object with an error field. A failed write reports its per-network result array on stdout and exits with 1. Agents documents the error shapes and terminal interruption codes.