WidgetStore CLI: let other AI agents use WidgetStore

The WidgetStore desktop app comes with a command-line tool, widgetstore. Other AI agents (Claude Code, Codex, Gemini CLI, Cursor…) and your own scripts can use it to work with WidgetStore:

• Cloud tools (the same tool set as our MCP server): read your space, change widgets, add records to My data, add to-dos, log focus, build spaces with AI… New capabilities on the website show up as commands automatically.
• This computer: start or stop the focus timer, pin a widget to the desktop, open a page or the launcher, show a notification, read AI usage, or have a local agent run a task.

Install

In the desktop app, open Agents → Command line → Install command-line tool:

• macOS: links /usr/local/bin/widgetstore (asks for your password). If you cancel, it uses ~/.local/bin and shows how to add it to your PATH.
• Windows: adds the app folder to your user PATH (no admin rights). Works in new terminals.
• Linux: the .deb / .rpm already installs /usr/bin/widgetstore; the AppImage links ~/.local/bin/widgetstore.

Open a new terminal and run widgetstore status.

Sign in

• On a computer with the desktop app (recommended): choose Connect account under Command line and approve the permissions in your browser (you can untick any). The authorization lives in your system keychain (on Linux, a file only you can read) and command-line processes never see the token — the desktop app makes the calls for them. Disconnect any time on the website under Settings → API & AI connections → Connected AI apps.
• Machines without the desktop app (servers / CI): create a personal token on the website and set WIDGETSTORE_TOKEN=wsp_…, or run widgetstore login --token - (reads it from stdin and stores it in the keychain).

Usage

widgetstore tools                    # every command (cloud + this computer)
widgetstore get_my_space --json      # machine-readable output
widgetstore add_record --help        # options of one command
widgetstore focus_start --minutes 25 --task "Weekly report"
widgetstore ask claude "Draft release notes from recent commits" --cwd ~/code/app --wait
widgetstore mcp                      # local MCP server (stdio)

• Options come from each tool’s JSON Schema: --name value, --flag / --no-flag, repeat a flag for arrays, or --args '{"…":…}' for everything at once. Use @file or @- (stdin) as a value.
• --json prints a fixed shape: {"ok":true,"tool":…,"data":…,"text":…} or {"ok":false,"error":{"code","message","exit"}}.
• Exit codes: 0 ok · 1 tool or server error · 2 usage error · 3 not signed in or missing permission · 4 desktop app not running (local commands) · 5 you denied it in the desktop app.

Add it to your agents

Run widgetstore mcp as a local MCP server (same tools) with one line:

Agent	Command / config
Claude Code	claude mcp add widgetstore -- widgetstore mcp
Codex CLI	codex mcp add widgetstore -- widgetstore mcp
Gemini CLI	gemini mcp add widgetstore widgetstore mcp
Cursor	~/.cursor/mcp.json: {"mcpServers":{"widgetstore":{"command":"widgetstore","args":["mcp"]}}}
opencode	opencode.json: {"mcp":{"widgetstore":{"type":"local","command":["widgetstore","mcp"]}}}

Or skip MCP and add a note to your project’s AGENTS.md / CLAUDE.md (the Command line page has a copy button):

## WidgetStore
- The `widgetstore` CLI is installed. Run `widgetstore tools --json` to see every command and its JSON schema.
- Call a tool with `widgetstore <tool> --option value --json` (exit code 0 = ok).
- Local actions (opening pages, pinning widgets, agent tasks) need the user to confirm in the WidgetStore desktop app. Cloud writes are logged and can be undone with `widgetstore undo`.

Safety

• Permissions are enforced on the server by the token’s scopes, and every change goes into the operation log where it can be undone (widgetstore undo). No command can delete data, change your account or spend money; tools that spend sparks are off for the command line by default (turn them on under Command line → Safety).
• Commands for this computer use a local channel that only your OS user can open, plus a random secret the desktop app creates on every start.
• Opening pages or the launcher, pinning widgets and starting agent tasks show a confirmation window in the desktop app, and only go ahead when you choose Allow. Under Command line → Safety you can trust “open” requests and read-only agent tasks; tasks that edit files or auto-approve always ask.
• Command-line processes never see your sign-in or tokens, and the desktop app never passes them to the agents it runs.