Commands

Pieces CLI Commands

Reference for every command available in the Pieces CLI, grouped by what you're trying to do.

The pieces help menu listing every command and flag.

Quick Reference

Run any command with the pieces prefix from a regular terminal (e.g., pieces ask "..."), or drop the prefix when you're inside pieces run loop mode. Type pieces help (or help inside loop mode) to view this list anytime.

Command	Description
`run`	Start the CLI in loop mode
`list`	List materials in your Pieces Drive
`list apps`	List registered applications
`list models`	List configured AI models
`create`	Create a material from clipboard
`modify`	Update the current material's content
`edit`	Rename or reclassify the current material
`share`	Generate a shareable link for a material
`delete`	Delete the current material
`execute`	Run a saved bash material
`ask`	Send a question to Conversational Search
`search`	Fuzzy-search materials and chats
`chats`	List all past conversations
`chat`	Show or switch conversations
`config`	View or edit CLI configuration
`commit`	Commit to GitHub with an auto-generated message
`login`	Log in to your Pieces account
`logout`	Log out of your Pieces account
`open`	Open PiecesOS or its Applet
`clear`	Clear the terminal screen
`version`	Show installed CLI and PiecesOS versions
`help`	Display the help menu
`onboarding`	Walk through first-run setup
`feedback`	Send feedback to the Pieces team
`contribute`	Contribute to the CLI project

Materials

Manage saved code, text, and bash materials in your Pieces Drive.

List every material in your Pieces Drive (alias: `drive`).

```bash
pieces list
```

List every application registered with PiecesOS.

```bash
pieces list apps
```

Create a new material from whatever's currently on your clipboard.

```bash
pieces create
```

Replace the content of the most recently selected material.

```bash
pieces modify
```

Rename or change the classification of the most recently selected material.

```bash
pieces edit
```

Generate a shareable URL for the most recently selected material. The CLI prints the URL and prompts you to open it in your browser.

```bash
pieces share
```

Delete the most recently selected material.

```bash
pieces delete
```

Run a saved bash material directly from the terminal.

```bash
pieces execute
```

AI & Search

Send questions to Conversational Search, search across your data, and pick which model responds.

Send a question to *Conversational Search*. Append flags to attach context from your Drive or local files.

```bash
pieces ask "How do I parse JSON in Python?"
```

Optional flags:

- `-m`, `--materials` — attach saved materials by index (e.g., `-m 1 2`)
- `-f`, `--file` — attach files or folders by absolute or relative path

```bash
pieces ask "Refactor this function" -f ./src/utils.py
```

Fuzzy-search materials and past chats.

```bash
pieces search "auth middleware"
```

Optional `--mode` flags:

- `--mode ncs` — Neural Code Search (semantic)
- `--mode fts` — Full-Text Search (literal)

```bash
pieces search "auth middleware" --mode ncs
```

Show every AI model configured for `ask`, and switch which one is active.

```bash
pieces list models
```

Conversations

Browse, switch between, and manage your Conversational Search threads.

List every past conversation, numbered for quick switching.

```bash
pieces chats
```

Show messages in your current conversation, or switch to another by number.

```bash
pieces chat
pieces chat 3
```

Conversation-management flags (use inside the active chat):

- `-n` — start a new conversation
- `-d` — delete the current conversation
- `-r "<name>"` — rename the current conversation

```bash
pieces chat -r "Project Ideas"
```

Configuration

View and edit CLI settings, including which code editor opens your config file.

Print your current Pieces CLI configuration to the terminal.

```bash
pieces config
```

Open your config file in the editor of your choice (e.g., `vim`, `code`). Changes save immediately.

```bash
pieces config --editor code
```

Account & Git

```bash
pieces login
```

Log out of your Pieces Cloud account.

```bash
pieces logout
```

Commit staged changes to GitHub with an auto-generated commit message. Add `-p` or `--push` to push immediately after.

```bash
pieces commit
pieces commit --push
```

Setup & System

Install the CLI, launch the loop, and access help, version, and feedback utilities.

Install the CLI with `pip` (or `conda`, if you prefer). Python must be set up correctly.

```bash
pip install pieces-cli
```

```bash
conda install pieces-cli
```

Start the CLI in loop mode—type commands and flags directly without the `pieces` prefix.

```bash
pieces run
```

Launch PiecesOS or its helper Applet.

```bash
pieces open
```

Clear the terminal screen.

```bash
pieces clear
```

Display installed versions of PiecesOS and the CLI.

```bash
pieces version
```

Display the help menu—the same one shown at the top of this page.

```bash
pieces help
```

Walk through first-run setup interactively.

```bash
pieces onboarding
```

Send feedback directly to the Pieces team.

```bash
pieces feedback
```

Open the contribution flow for the open-source CLI project.

```bash
pieces contribute
```

Next Steps

Want to see these commands in context? Read about Conversational Search for ask, search, and chat, Pieces Drive for material commands, or the full Configuration walkthrough.