talkbar-cli

talkbar-cli is the command-line program that ships with TalkBar. It runs the same operations an AI assistant can run over MCP, from a terminal, a script or an AI agent that can run commands. It also starts the MCP server and runs exports in the background.

Before you start

• talkbar-cli ships with TalkBar. Settings → MCP Access → Executable path shows where. Use Add to PATH there to run it by name from any terminal. See Where talkbar-cli is installed.
• It opens your TalkBar data folder, or the folder in TALKBAR_DATA_ROOT when that is set. Find the actual path in Settings → MCP Access → Data root. The app can be open or closed.
• It does what you type, as you. The MCP Access switches do not apply to it, but administrator rules and plan limits do. See What the command line ignores.

talkbar-cli --version
talkbar-cli --help
talkbar-cli tools --help

Examples use a POSIX shell on macOS or PowerShell on Windows. If a shell handles JSON quotes differently, use --args-file.

Commands

talkbar-cli call … (without tools) is a usage error that suggests talkbar-cli tools call.

Global options

These work before or after the command:

List and inspect operations

talkbar-cli tools list
talkbar-cli tools list --compact
talkbar-cli tools info notes.create
talkbar-cli --output json tools info notes.create

• tools list prints a table of id, kind (read or mutation), category and description, then a total. With --output json, each operation comes with its title, description, category, kind, default MCP switch and full input schema.
• tools list --compact prints one line per operation: id, kind (read or change) and summary, separated by tabs. It is the cheapest index for scripts and AI agents.
• tools info <id> prints the operation's description, whether it is on by default in MCP, a usage line, and the arguments it accepts as a JSON Schema. Arguments are camelCase JSON.

The list holds every operation an administrator has not blocked. For each operation's arguments and results, see the operations reference.

Run one operation

Pass the arguments as a JSON object:

talkbar-cli tools call sessions.list --args '{"limit":5}'
talkbar-cli tools call notes.get --args '{"noteId":"note-k2v9w8x7c6b5n4m3l2j1h0g9"}'

workspaceId is optional, as in MCP: without it, the workspace open in the app is used.

Arguments from standard input or a file

Long text, such as a note body, is easier to pass through standard input or a file than on the command line:

Get-Content note.json -Raw | talkbar-cli tools call notes.create --args -

cat note.json | talkbar-cli tools call notes.create --args -

talkbar-cli tools call notes.create --args-file note.json

{
  "title": "Weekly sync follow-ups",
  "markdown": "## Follow-ups\n\n- Send the revised quote to Dana\n- Book the next sync"
}

Files and piped text saved with a UTF-8 byte order mark, as Windows PowerShell 5 writes them, are read correctly.

Run a batch

tools batch runs many operations in one process, in order. It is faster than one command per operation, and the open app refreshes once for all of them.

'[{"tool":"notes.list","args":{"limit":3}},{"tool":"sessions.list","args":{"limit":5}}]' | talkbar-cli tools batch
talkbar-cli tools batch --file calls.json --stop-on-error

• Input is a JSON array of {"tool", "args"}, or the MCP form {"calls": [...], "stopOnError": true}. It comes from --file, or from standard input when --file is left out or is -.
• There is no 20-operation cap, as there is in MCP. [] prints [].
• --stop-on-error (or "stopOnError": true) stops at the first failed operation.
• The output is always one JSON array, one entry per operation that ran:

[
  { "tool": "notes.list", "ok": true, "result": { "items": [], "nextCursor": null, "hasMore": false, "totalCount": 0 } },
  { "tool": "sessions.get", "ok": false, "error": { "code": "not_found", "message": "Session not found in workspace" } }
]

The command exits with 1 when any operation failed, after printing every result. Standard error then says how many failed, for example 1 of 2 operations failed.

Search

search is the app's universal search from the terminal, transcript snippets included:

talkbar-cli search pricing review
talkbar-cli search "renewal date" --kinds session,note --limit 10
talkbar-cli search budget --match any --output json

The table output groups matches by kind, each with its title, a snippet and its app link. --output json prints the same object as talkbar_find.

Serve MCP

talkbar-cli serve --transport stdio

Starts the MCP server on standard input and output. stdio is the only transport and the default. Your AI app runs this command itself, with TALKBAR_DATA_ROOT set; see Set up MCP. Unlike the other commands, serve follows every switch in Settings → MCP Access. --output has no effect on it.

Exports

The exports command delivers queued exports, the same work the app does while it runs. Set up destinations in the app first; see Exports.

talkbar-cli exports run --workspace WORKSPACE_ID --batch BATCH_ID --wait
talkbar-cli exports worker
talkbar-cli exports worker --drain

exports commands need --workspace (find it with tools call workspace.list). exports notion connect refuses to read the token from the keyboard, so it is never shown on screen; pipe it from your password manager instead:

Get-Secret -Name TalkBarNotionToken -AsPlainText | talkbar-cli exports notion connect --workspace WORKSPACE_ID --destination DESTINATION_ID

To queue an export in the first place, use tools call exports.enqueue. See Export a session.

Output and errors

• Standard output holds only results. Results are JSON: pretty-printed at a terminal, compact when piped to another program or an AI agent.
• Errors go to standard error as a line starting with Error:. For a wrong argument, it also suggests tools info <id>; for an unknown operation, tools list.
• With --output json, a failed command also prints the error on standard output, in the same shape MCP uses:

{"error":{"code":"not_found","message":"Note not found in workspace"}}

tools call prints the operation's own code (not_found, invalid_arguments, plan_limit and so on); other failures, such as a wrong --db path or an administrator rule, print "code": "failed". tools batch prints only its results array. Read standard output on its own; don't merge standard error into it (2>&1).

Exit codes

For AI agents with a shell

An agent that can run commands, such as Claude Code or Codex, can use talkbar-cli instead of MCP. It costs no tool definitions, and one command can run many operations.

• Get the index with talkbar-cli tools list --compact, and one operation's arguments with talkbar-cli tools info <id>.
• Batch instead of looping: one tools batch replaces many tools call runs, and each run of talkbar-cli takes time to start.
• Send long text through --args - or --args-file.
• Branch on --output json error codes, not on the wording of messages.
• Remember that the command line ignores the MCP Access switches. Give the agent this route only if you are comfortable with it running any operation you could run yourself.

The app refreshes itself

After a successful write, talkbar-cli (and the MCP server) tells the running TalkBar app what changed, over a private local channel. The app refreshes the screens and the tray menu that show those items. When the app is closed, nothing is sent and nothing slows down.

Related

• MCP overview
• Access and permissions
• Errors and limits
• Examples
• Operations reference