Curio CLI

Installation and Integrations

Curio supports automation through a separately downloaded command line tool named curio. The CLI can query projects, read figure and Organizer item properties, inspect sections, assets, and tags, update selected content, export results, import files and content, navigate directly to figures or idea spaces, install AI agent skill files for AI coding assistants, and run a stdio MCP server for AI clients.

The CLI is designed for Terminal users, scripts (ex: shell, Python), AI agents (ex: ChatGPT Desktop, codex, claude, agy, OpenClaw), and MCP hosts (ex: Claude Desktop). It prints JSON responses, JSONL for batch output, uses the same query language as Curio’s Search shelf and Quick Find, and works either with the running Curio app or directly against a .curio project file on disk.

Installing the CLI

The Curio CLI is a separate download from the main Curio application. Installing the Curio app does not automatically install the curio command line tool.

The Curio CLI installer is code-signed with our Apple Developer ID certificate and notarized by Apple, which means macOS has verified that it comes from Zengobi and is free of known malicious content.

You can install or update the CLI from within Curio using the Curio > Install Curio CLI or Curio > Update Curio CLI menu item.

• In the website edition, Curio downloads the signed installer, verifies it, reveals it in Finder, and opens it.
• In the Mac App Store edition, Curio opens the CLI web page so you can download and install it yourself.

Alternatively, to download the latest CLI release directly, visit: https://www.zengobi.com/curio/cli/download

Verifying the Install

After installing it, open Terminal and run:

curio --version

The signed installer places the release payload like this:

/
|-- Library/
|   `-- Application Support/
|       `-- CurioCLI/
|           |-- bin/
|           |   |-- curio
|           |   `-- Frameworks/
|           |-- skills/
|           |   |-- curio/
|           |   |-- curio-query/
|           |   `-- curio-mcp/
|           `-- resources/
|               `-- MCPB/
`-- usr/
    `-- local/
        `-- bin/
            `-- curio -> /Library/Application Support/CurioCLI/bin/curio

The CLI stores its update cache in ~/Library/Application Support/CurioCLI/config.json. User-facing CLI preferences live separately in ~/.curio/settings.json; see CLI Settings.

If Terminal still reports that curio cannot be found, make sure the installer completed successfully and verify that /usr/local/bin/curio exists.

Updating the CLI

To review what changed in recent CLI releases, see the Curio CLI release notes.

The CLI checks for updates automatically once per day before handling normal commands such as query and get. The first such command of the day fetches the latest CLI release metadata and caches it locally; later commands that same day reuse that cached result.

If a newer CLI release is available, the CLI prints an update notice to standard error before handling the request and tells you how many days remain before the update becomes mandatory. For the first 30 days after a newer CLI release is published, the command still runs. After that 30-day grace period, the CLI stops the request and returns an error until you upgrade.

Use this command at any time to refresh the update state immediately:

curio update

If an update is available and the CLI was installed with the signed installer, curio update asks whether to download and launch the installer. Press y or Return to download the installer to your Downloads folder, reveal it in Finder, and open it. Press any other key to leave the installer untouched.

Before opening a downloaded installer, the CLI verifies the package against the SHA-256 checksum in the update metadata, checks its installer signature with macOS pkgutil, requires the Zengobi Developer ID Installer identity, and runs a Gatekeeper installer assessment with spctl. If any verification step fails, the CLI removes the downloaded package and does not open it.

When curio update is run from a script, through redirected input/output, or through an MCP host, it does not prompt; it only reports the update details and download URL.

Some commands remain available even when an update is required: curio help, curio --help, curio --version, curio fields, curio skills, curio settings, curio claude, and curio update.

Each CLI release also declares the minimum Curio app version it requires. If your installed Curio app is too old, the CLI will refuse the request and tell you which Curio version is required.

After Installing the CLI

You can use curio on its own from Terminal, scripts, or other tools that can run command line programs. If you want an AI coding assistant to work with Curio projects more directly, you may also want to:

• Install AI Agent Skills with the Installing skills workflow, which places CLI-oriented skills in the shared ~/.agents folder or a platform-specific folder for agents such as Claude Code, Codex, or Antigravity CLI.
• Install the Claude Desktop connector with curio claude install for Claude Desktop’s Chat and Cowork tabs.

Two Ways to Work

By default, curio talks to the running Curio app. This mode supports everything, including selection-based queries, Organizer creation, property changes, import/export, and navigation by UUID.

curio query "#active" --fields id,title

You can also point the CLI at a project file directly using --project:

curio query --project ~/Documents/MyProject.curio "#active" --fields id,title

This direct mode is read-only, so it is ideal for scripts and automations that need to inspect a project without launching Curio first.

Finding Help

The CLI is self-documenting. These commands are the quickest way to inspect the capabilities of the version you have installed:

curio help
curio --help
curio fields
curio fields due_date
curio tags
curio settings list
curio skills list
curio claude doctor
curio mcp-server --log ~/Library/Logs/curio-mcp.log
curio status
curio --version

Use --verbose with most commands if you want diagnostic details about transport selection, repository discovery, or activation handling.

CLI Settings

The CLI supports user settings in:

~/.curio/settings.json

Use curio settings to inspect and update the file instead of editing it by hand:

curio settings list
curio settings get query.max_chars
curio settings set query.max_chars=4000
curio settings set output.pretty_json=no
curio settings remove query.max_chars
curio settings path
curio settings reveal

Settings are addressed by dotted keys and stored as nested JSON. Explicit command-line flags still win over settings. Boolean settings accept true/false, yes/no, on/off, and 1/0. Use curio settings reveal to create the settings file if needed and reveal it in Finder.

Setting	Type	Default	Description
query.max_chars	integer	unset	Default text truncation for curio query; explicit --max-chars wins.
output.pretty_json	boolean	true	Pretty-print normal JSON responses. Set to no for compact script output.
output.color	string	auto	Terminal styling: auto, always, or never.
diagnostics.verbose	boolean	false	Enable verbose diagnostics by default.
batch.continue_on_error	boolean	false	Continue batch execution after a failed line unless stopped by another fatal condition.
mcp.log_path	string	unset	Default log path for curio mcp-server; explicit --log wins.
transport.send_timeout_seconds	number	10.0	Timeout for sending requests to the running Curio app.
transport.receive_timeout_seconds	number	10.0	Timeout while waiting for the running Curio app to reply.
curio.install_preference	string	auto	Preferred Curio install for direct project reads when both editions are present: auto, direct, or mas.

AI Agent Skills

The Curio CLI bundles skill files that teach CLI-capable AI agents how to use the curio command effectively. The installable CLI skills are linked into each platform’s skill directory as symlinks pointing at the bundled files under /Library/Application Support/CurioCLI/skills/, so they always reflect the latest installed CLI version automatically.

Two skills are installed by curio skills install ...:

• curio — general CLI skill covering all commands, transport modes, fields, workflows, and error handling.
• curio-query — query language skill covering boolean logic, tags, dates, comparisons, and result-shaping commands.

A third bundled skill, curio-mcp, remains in the installation for reference and for legacy/manual hosts that support separate uploaded skill packages. Claude Desktop users should normally use the MCPB connector installed by curio claude install instead of uploading curio-mcp-upload.zip.

Codex and Claude Code can invoke these skills automatically when your request matches the skill’s description, or you can invoke them explicitly. In Codex, mention a skill with $curio or $curio-query, or type /skills and choose the skill from the Skills UI. In Claude Code, use /curio or /curio-query. See OpenAI’s Codex skills documentation and Anthropic’s Claude Code skills documentation for platform-specific details.

Listing platforms

Use curio skills or curio skills list to see which platforms are available and whether skills are currently installed:

curio skills list

The output shows each supported platform with its install status: installed, partial, or not installed. Install status is determined dynamically from the platform’s current skill symlinks, not from a separate manifest. Platforms are detected automatically based on whether their configuration directory exists (e.g., ~/.agents/ for the common agents folder or ~/.claude/ for Claude Code). When a platform is partial, the CLI prints which installable skills are missing.

Installing skills

Install skills into the common ~/.agents folder used by most AI agents, including ChatGPT/Codex and Gemini/Antigravity but not Claude:

curio skills install agents

Or install only for a specific platform:

curio skills install claude
curio skills install codex
curio skills install agy
curio skills install antigravity

Or auto-detect all installed platforms and install skills for all of them at once:

curio skills install --all

Each install creates symlinks from the platform’s skill directory to the bundled skill files. For example, curio skills install agents creates:

• ~/.agents/skills/curio → /Library/Application Support/CurioCLI/skills/curio
• ~/.agents/skills/curio-query → /Library/Application Support/CurioCLI/skills/curio-query

The bundled curio-mcp skill is not installed as a platform symlink by this command. It remains available in the bundled skills folder as legacy/reference material, but Claude Desktop users should normally install the MCPB connector with curio claude install.

Installing is idempotent — running it again when skills are already installed is a safe no-op.

If a non-CLI-managed file or directory already exists at the symlink location, the installer skips it and prints a warning rather than overwriting your data.

Uninstalling skills

Remove skills for a specific platform:

curio skills uninstall claude

Or uninstall CLI-managed skill symlinks for all Curio CLI-managed platforms:

curio skills uninstall --all

Uninstall only removes symlinks that point to the CLI’s bundled skills directory. It will not remove files or symlinks that were created manually or by another tool.

Browsing bundled skills

To open the bundled skills folder in Finder for manual inspection or copying to an unsupported platform:

curio skills reveal

Supported platforms

Platform	Skill directory
Agents (common folder used by most AI agents)	~/.agents/skills/
Claude Code	~/.claude/skills/
Codex	~/.codex/skills/
Antigravity CLI (agy)	~/.gemini/skills/
Antigravity Desktop	~/.antigravity/skills/

Platforms that support manual skill copying can use curio skills reveal to access the bundled skill files directly. The ChatGPT desktop app can use these skills when they are installed in either ~/.agents/skills/ or ~/.codex/skills/.

Skills subcommands

curio skills
curio skills install <platform>
curio skills install --all
curio skills uninstall <platform>
curio skills uninstall --all
curio skills reveal

MCP Server

The same curio binary can also run as a stdio MCP server:

curio mcp-server
curio mcp-server --log ~/Library/Logs/curio-mcp.log

This mode is intended to be launched by an MCP host such as Claude Desktop. It is not a daemon and does not run as a background service. The host starts curio mcp-server on demand, communicates with it over stdin/stdout for the life of the session, and then shuts it down.

The MCP server exposes Curio commands as MCP tools with shared command-runner behavior, so the MCP surface stays aligned with the CLI. Tool names are MCP-style names such as curio_query, curio_get, curio_create, curio_move, curio_batch, curio_set, curio_status, curio_fields, and curio_docs.

MCP tool	CLI equivalent	Purpose
curio_query	curio query	Search figures using Curio’s query language or inspect a live selected target.
curio_get	curio get	Read properties for a figure, idea space, or Organizer item.
curio_set	curio set	Update writable properties on a figure, idea space, or Organizer item.
curio_create	curio create	Create Organizer sections, folders, and idea spaces in the running app.
curio_move	curio move	Move a figure to a canvas coordinate or move an Organizer item using placement hints.
curio_batch	curio batch	Run a command batch file or inline batch content with pseudo-variable references.
curio_fields	curio fields	List available automation fields.
curio_field_detail	curio fields <name>	Show type, writability, and usage guidance for one field.
curio_docs	bundled MCP docs	Read bundled MCP guidance when resources are not exposed directly.
curio_tags	curio tags	List actual tags in the current or offline project.
curio_export	curio export	Export a figure or live selection to a file or the clipboard.
curio_import	curio import	Import a file, inline content, or Spread PDF pages.
curio_navigate	curio navigate	Navigate the running Curio app to a URL, project path, idea space, section, or figure.
curio_sections	curio sections	List the Organizer section hierarchy.
curio_assets	curio assets	List figures and assets within a section or project.
curio_status	curio status	Check app state, open projects, transport mode, and selected target availability.
curio_help	curio help	Show CLI help text.
curio_version	curio --version	Show CLI version information.
curio_update	curio update	Check CLI update status and report available update details.

curio_docs is a read-only tool that returns bundled MCP guidance for hosts that do not expose MCP resources directly to the chat model. It supports these topics: overview, query-language, workflows, and transport-modes.

The server also exposes MCP-native guidance:

Resources via curio-mcp://docs/... URIs such as:

• curio-mcp://docs/overview
• curio-mcp://docs/query-language
• curio-mcp://docs/workflows
• curio-mcp://docs/transport-modes

Prompts for common workflows such as:

• build_curio_query
• inspect_curio_selection
• update_curio_item

These resource URIs are MCP-internal identifiers, not Curio app deep links. They are passed from the MCP client back to the Curio MCP server during resources/read; they are not opened by macOS or by the Curio app.

Manual MCP Host Configuration

Claude Desktop users should normally install the packaged connector with curio claude install, described below. For other MCP hosts, or for users who want to configure Claude Desktop manually, use this stdio server configuration:

{
  "mcpServers": {
    "curio": {
      "command": "/Library/Application Support/CurioCLI/bin/curio",
      "args": ["mcp-server"]
    }
  }
}

If your host expects just the server entry rather than a full mcpServers object, use:

{
  "command": "/Library/Application Support/CurioCLI/bin/curio",
  "args": ["mcp-server"]
}

Use the installed binary under /Library/Application Support/CurioCLI/bin/curio for host-launched MCP connections. That path remains stable across CLI updates.

Integrating with AI Clients

Agents

Many AI agent tools, including ChatGPT/Codex and Gemini/Antigravity but not Claude, use the common ~/.agents/ folder for shared items such as skills.

curio skills install agents

This installs the CLI-oriented Curio skills under ~/.agents/skills/.

You can remove the Curio CLI skills with curio skills uninstall agents To remove all Curio CLI skill installations at once, use curio skills uninstall --all.

Codex CLI

For the Codex CLI (codex), the simplest integration today is CLI-based skills. Install into the common ~/.agents folder if you want the Curio skills visible to most AI agents:

curio skills install agents

Or install only for Codex:

curio skills install codex

The Codex-specific command installs the CLI-oriented curio and curio-query skills under ~/.codex/skills/.

You can verify the installation by launching codex and typing $curio or $curio-query to invoke a Curio skill directly. Typing a dollar sign $ shows an autocomplete popup of installed skills, where you should see Curio’s skills in the list. You can also type /skills to list or manage the installed skills. Codex can also choose a skill automatically when your request matches the skill’s description.

Since codex can call CLI tools directly, unlike apps which rely on MCP connections, using these CLI-oriented skills are much more efficient and work best for agents like codex.

You can remove the Curio CLI skills with curio skills uninstall codex

ChatGPT Desktop

The ChatGPT desktop app offers both Codex and Work modes. Use the selector in the top-left corner of the window to switch between them.

To make Curio CLI skills available in ChatGPT, install them into the shared ~/.agents/skills/ folder if you want them available to most AI agents:

curio skills install agents

Or install them only for ChatGPT’s Codex mode:

curio skills install codex

You can verify the installation in ChatGPT by opening Settings, choosing Plugins in the sidebar, and then selecting Skills. The Curio CLI skills should appear there when they are installed in either folder.

First Prompt

After installing the skills, a good first prompt in ChatGPT is:

What can you do with the Curio skills available to you? Summarize what you can do with my Curio projects.

ChatGPT Web

When you use ChatGPT on the web instead of the ChatGPT desktop app, you can connect to Curio through OpenAI’s Secure MCP Tunnel. This is useful when you want ChatGPT’s web interface to use Curio’s local stdio MCP server without exposing your Mac or Curio project data through a public inbound network port.

Secure MCP Tunnel

In this setup:

1. Curio provides the local MCP server command: /Library/Application Support/CurioCLI/bin/curio mcp-server
2. OpenAI’s tunnel-client runs on your Mac and launches that command over stdio.
3. tunnel-client opens an outbound HTTPS connection to OpenAI’s tunnel service.
4. ChatGPT sends MCP requests through the tunnel, and tunnel-client forwards them to Curio locally.

Because the connection is outbound-only, you do not need to open a firewall port or run a public web server for Curio. However, ChatGPT can still request Curio data through the MCP tools you allow, so treat this as giving ChatGPT controlled access to your local Curio automation surface.

Requirements

You need:

• The Curio CLI installed and up to date.
• OpenAI access to Secure MCP Tunnel and ChatGPT custom connectors.
• A tunnel created in OpenAI’s Platform tunnel settings.
• A runtime OpenAI API key with permission to read and use that tunnel.
• OpenAI’s tunnel-client utility installed on the Mac that can run Curio.
• The Curio app running if you want ChatGPT to use live-app features such as the current selection, current idea space, navigation, import/export, or property changes.

For read-only offline queries against a .curio project file, Curio’s --project mode can still be used by MCP tools that expose project_path. For anything involving the current selection or changes to your project, run tunnel-client as your normal logged-in Mac user while Curio is open.

Setup outline

Follow OpenAI’s official Secure MCP Tunnel reference page to create the tunnel and install tunnel-client. When creating the local stdio profile, point --mcp-command at Curio’s installed MCP server:

export CONTROL_PLANE_API_KEY="sk-..."

tunnel-client init \
  --sample sample_mcp_stdio_local \
  --profile curio \
  --tunnel-id tunnel_0123456789abcdef0123456789abcdef \
  --mcp-command "/Library/Application Support/CurioCLI/bin/curio mcp-server"

Then validate and run the tunnel:

tunnel-client doctor --profile curio --explain
tunnel-client run --profile curio

Keep tunnel-client run --profile curio running while ChatGPT discovers or uses the Curio connector. In ChatGPT’s connector settings, create a custom connector, choose Tunnel as the connection type, and select or paste the tunnel ID you created in OpenAI Platform.

To verify the connection, start with read-only Curio tools such as status, fields, docs, and query. Only enable write/delete tools such as set, import, export, navigate, create, move, or batch if you are comfortable with ChatGPT asking to perform those actions against your local Curio projects.

Claude Code CLI

For the Claude Code CLI (claude), the simplest integration today is CLI-based skills:

curio skills install claude

This installs the CLI-oriented curio and curio-query skills under ~/.claude/skills/.

You can verify the installation by launching claude and typing /curio or /curio-query to invoke a Curio skill directly, or /skills to list all installed skills. Claude Code can also choose a skill automatically when your request matches the skill’s description.

Since Claude Code can call CLI tools directly, unlike apps which rely on MCP connections, using these CLI-oriented skills are much more efficient and work best for agents like claude.

You can remove the Curio CLI skills with curio skills uninstall claude To remove all Curio CLI skill installations at once, use curio skills uninstall --all.

Claude Desktop

Claude Desktop has three tabs, each with different integration behavior:

• The Code tab behaves identically to the Claude Code CLI ( claude ) and reads skills from ~/.claude/skills/ directly.
• Chat and Cowork tabs talk to Curio over MCP using the Curio’s Claude Connector.

Code Tab

Because the Code tab behaves identically to the Claude Code CLI, setup is the same as for claude - just install the CLI-oriented skills:

curio skills install claude

This makes the curio binary callable directly through the installed skills, with no MCP layer required. See the Claude Code CLI section above for details.

Chat and Cowork Tabs

The Chat and Cowork tabs have to go through the Curio CLI’s MCP interface over stdio.

The easiest setup is the packaged Curio Claude Connector:

curio claude install

This creates a .mcpb Claude Connector package, opens it in Claude Desktop, and lets Claude Desktop install the Curio connector with its tool and prompt metadata already included. No claude_desktop_config.json edit and no manual Skills upload is required.

Alternatively, you can also create the package without opening it immediately:

curio claude package
curio claude package --output ~/Desktop/curio.mcpb

curio claude package reveals the resulting .mcpb file in Finder by default. Use --no-reveal if you are scripting package creation.

First Prompt

After installing the connector, a good first prompt in Claude Desktop is:

What Curio MCP tools, prompts, and resources are available? Summarize what you can do with my Curio projects.

Troubleshooting the Claude Connector

To verify the installed CLI and connector prerequisites, run:

curio claude doctor

doctor checks the installed curio path, connector template resources, Claude Desktop availability, whether an old mcpServers.curio entry still exists, and whether the MCP server answers an initialize request.

In Claude Desktop’s Connectors UI, Curio’s tools are grouped as read-only tools and write/delete tools. You can set read-only tools such as Query, Get, Docs, and Status to Always Allow, if you wish, so Claude does not ask before performing read-only actions. Tools such as Set, Import, Export, and Navigate can remain set to Needs Approval.

To uninstall the packaged connector from Claude Desktop:

1. In Claude Desktop, click Customize in the sidebar.
2. Click Connectors .
3. Select the Curio connector.
4. Click Uninstall .

Manual Claude Desktop Configuration

The packaged connector is preferred. If you need the older manual setup, edit claude_desktop_config.json, typically located at:

~/Library/Application Support/Claude/claude_desktop_config.json

Add mcpServers to the existing top-level object:

{
  "mcpServers": {
    "curio": {
      "command": "/Library/Application Support/CurioCLI/bin/curio",
      "args": ["mcp-server"]
    }
  }
}

If the file already contains preferences or other top-level objects, add mcpServers beside those objects, separated with a comma.

To remove a manual configuration, quit Claude Desktop, remove the curio entry from mcpServers, then relaunch Claude Desktop. If nothing else is left inside mcpServers, remove the mcpServers key as well.

Antigravity CLI

For Antigravity CLI (agy), formerly known as Gemini CLI (gemini), the simplest integration today is CLI-based skills:

curio skills install agy

This installs the CLI-oriented Curio skills under ~/.gemini/skills/.

You can verify the installation by launching agy and typing /curio to see the Curio skills or /skills to list all installed skills.

Since Antigravity CLI can call CLI tools directly, unlike apps which rely on MCP connections, using these CLI-oriented skills are much more efficient and work best for agents like agy.

You can remove the Curio CLI skills with curio skills uninstall agy To remove all Curio CLI skill installations at once, use curio skills uninstall --all.

Antigravity Desktop

Antigravity Desktop uses a separate skill directory from Antigravity CLI:

curio skills install antigravity

This installs the CLI-oriented Curio skills under ~/.antigravity/skills/.

You can remove the Curio CLI skills with curio skills uninstall antigravity To remove all Curio CLI skill installations at once, use curio skills uninstall --all.