CoCo CLI reference¶

Command line reference for CoCo CLI. CoCo CLI operates in two modes:

• Interactive mode (default): Start a persistent session where you type prompts and slash commands at an interactive prompt. CoCo maintains conversation context across multiple exchanges.
• Batch mode: Pass a single prompt on the command line or from a file. CoCo processes it and exits without starting an interactive session.

The sections below cover the startup command, CLI options shared by both modes, subcommands you run before entering a session, interactive-mode commands you use within a session, and batch-mode usage.

Starting CoCo¶

CLI options¶

Connections must be defined in ~/.snowflake/connections.toml. See CoCo CLI for connection setup. Session IDs are shown at startup and at exit, and they are stored in ~/.snowflake/cortex/conversations/.

--bypass and --dangerously-allow-all-tool-calls are aliases of the same option. Omit the value of -r, --resume to open the resume picker instead of naming a session. Use --allowed-tools to pre-approve specific tools (for example, "Bash(git *)" to approve all git commands); use --disallowed-tools to prevent specific tools from being offered to the model at all.

See CoCo CLI cloud sandbox for details on --cloud, --no-workspace, and --github. --cloud optionally takes a workspace name (DATABASE.SCHEMA.NAME) to mount; --github takes the name of a Snowflake secret (DATABASE.SCHEMA.SECRET) holding a GitHub personal access token, and implies --cloud.

Examples¶

Start with working directory:

cortex -w /path/to/project

Resume last session with specific connection:

cortex --continue -c production

One-off prompt (JSON output):

cortex -p "List all Python files" --output-format stream-json

Commands¶

These subcommands run from your shell before or instead of starting an interactive session. They are distinct from the slash commands (like /mcp) that you type inside an interactive session.

update¶

Update CoCo CLI to the latest version.

exec¶

Use exec to run CoCo CLI non-interactively, which is useful in continuous integration and continuous delivery (CI/CD) pipelines. Plan mode is always disabled and interactive prompts are automatically rejected.

mcp¶

Manage Model Context Protocol (MCP) server connections from the command line.

The add subcommand accepts the following options:

See MCP (Model Context Protocol) for details.

Interactive mode¶

Interactive mode is the default when you run cortex without -p or exec. CoCo opens a persistent session where you type natural-language prompts and slash commands at the > prompt. The agent processes your request, potentially using multiple tools, and then returns to the prompt for your next input.

Keyboard shortcuts and slash commands described in this section work only in interactive mode. They don’t apply in batch mode or inside a file passed to cortex exec --file.

Keyboard shortcuts¶

These shortcuts are active at the interactive prompt and while the agent is working:

Slash commands¶

Slash commands are special commands you type at the interactive prompt. They start with / and control CoCo’s behavior without being sent to the AI model as a prompt. Slash commands work only in interactive mode.

Session management¶

Model and mode¶

Snowflake and data¶

Development tools¶

Configuration¶

Extensibility¶

Utilities¶

Session storage¶

See CoCo CLI Settings for configuration details.

Command details¶

/sql: Execute SQL query¶

Basic query:

/sql SELECT * FROM users

With row limit:

/sql SELECT * FROM large_table --limit 1000

Multi-line queries (use Ctrl+J for newlines):

/sql SELECT
  customer_id,
  SUM(amount) as total
FROM orders
GROUP BY customer_id

Results open automatically in the table viewer (Ctrl+T).

/worktree: Git worktrees¶

Git worktrees let you work on multiple branches simultaneously without switching back and forth. CoCo creates worktrees under your project directory by default (in a .worktrees/ subdirectory or alongside your main checkout, depending on your git configuration).

/sandbox: Sandbox control¶

CoCo’s sandbox isolates shell commands in a restricted environment so they can’t modify files outside your working directory or access sensitive system resources. This is a CoCo-specific security feature. The container sandbox uses Docker, while the runtime sandbox uses OS-level restrictions (macOS sandbox or Linux namespaces).

To run tools in a Snowflake-managed container instead of on your machine, start CoCo CLI with --cloud. See CoCo CLI cloud sandbox.

/mcp: MCP servers¶

/mcp takes no subcommands. It opens an interactive viewer that lists every configured server and lets you start, stop, reconnect, authenticate, edit, and remove servers from within the session. For non-interactive management, use the cortex mcp subcommands described in mcp.

Batch mode¶

Batch mode runs a single prompt without starting an interactive session. CoCo processes the request, prints the result, and exits. This is useful for scripting, CI/CD pipelines, and one-off questions where you don’t need a back-and-forth conversation.

Use -p for inline prompts or cortex exec for prompts from files or stdin. Slash commands don’t work in batch mode because there’s no interactive prompt.

Exit codes¶

CoCo CLI returns 0 on success and a non-zero value on failure. It doesn’t guarantee a stable mapping of specific non-zero codes to error categories, so scripts should test only for zero versus non-zero. Error details are written to standard error.

Configuration and setup¶

Updating CoCo CLI¶

CoCo CLI updates itself when a new version is available. You can also manually update to the latest version by issuing cortex update. Issue cortex update <version> to install the specified version.

To disable automatic updates, edit ~/.snowflake/cortex/settings.json and add "autoUpdate": false.

Manually adding a connection¶

To manually create or edit the ~/.snowflake/connections.toml file to define your connection, follow these steps:

1. Create the ~/.snowflake/connections.toml file if it doesn’t already exist.

   Copy code

   mkdir -p ~/.snowflake
   touch ~/.snowflake/connections.toml
   

2. Use the chmod command to set its permissions so that only you can read and write it.

   Copy code

   chmod 600 ~/.snowflake/connections.toml
   

3. Open the file in a text editor (here, nano).

   Copy code

   nano ~/.snowflake/connections.toml
   

4. Add lines like the following to define a connection. Enter the name of the connection in place of myaccount and replace the placeholder values with your Snowflake account details. Use browser-based SSO (external browser authentication) or PAT (programmatic access token). You can obtain a PAT from Snowsight (see Using programmatic access tokens for authentication). Include only the authenticator value or password value, depending on the authentication method you choose.

   Copy code

   [myaccount]
   account       = "<ACCOUNT>"
   user          = "<USERNAME>"
   authenticator = "externalbrowser" # For browser-based SSO; omit for PAT
   password      = "<PAT>"           # For PAT authentication; omit for SSO
   warehouse     = "<WAREHOUSE>"
   role          = "<ROLE>"
   database      = "<DATABASE>"
   schema        = "<SCHEMA>"
   

5. Save and close the file.

Setting up shell completions¶

To give your shell the ability to auto-complete CoCo CLI commands and options, use one of the following methods.

The quickest way is to let CoCo CLI install the completion script for you. Issue the following command to install for your current shell, or add --all to install for every supported shell:

cortex completion install

To install for a specific shell, pass --shell:

cortex completion install --shell zsh

Alternatively, generate the script yourself and write it to the location your shell expects:

Restart your shell with exec $SHELL after you install or generate the completion script.

Directory structure¶

CoCo CLI stores its configuration and state under your home directory as follows. It creates files and directories as they are needed, so not all of them are present on a new installation.

~/.snowflake/cortex/
   ├── settings.json          # Main configuration (includes hook configuration)
   ├── mcp.json               # MCP server configs
   ├── hooks.json             # Global hook configuration
   ├── conversations/         # Session history
   ├── skills/                # Global skills
   ├── commands/              # Custom commands
   ├── profiles/              # Team profiles
   └── cache/                 # Temporary cache

Troubleshooting¶

Following are common error messages you may encounter during installation and setup.

Command not found¶

Make sure that the installation directory ~/.local/bin is included in your PATH environment variable. For example, if you are using bash, issue the following commands:

export PATH="~/.local/bin:$PATH"
echo 'export PATH="~/.local/bin:$PATH"' >> ~/.bashrc

Permission denied¶

Make sure that the cortex executable has execute permissions. Issue the following command:

chmod +x ~/.local/bin/cortex

Connection errors¶

Make sure that the connection file ~/.snowflake/connections.toml exists and contains valid connection details.

cat ~/.snowflake/connections.toml

Try invoking the cortex command with a connection explicitly specified using the -c option. For example:

cortex -c myaccount

See also¶

CoCo CLI

Installation, setup, and first prompts

CoCo CLI Settings

Configuration file reference

CoCo CLI workflow examples

Capabilities and workflow examples