Pieces CLI Prerequisites
Before installation, you’ll need:
-
PiecesOS: The power engine behind the Pieces CLI and the rest of the Pieces Suite. Learn more about PiecesOS.
-
Python 3.xx: Python is required to be installed on your development machine.
PiecesOS must be installed to use the Pieces CLI and ensure it works properly.
We also suggest using the Pieces for Developers Desktop App for better functionality.
Installing the Pieces CLI
Follow the instructions below to install the Pieces CLI and any required dependencies.
Install Python
Head to Python’s website and download the version that best suits your environment.
After downloading the Python version 3.xx, you will be guided through the installation process. Follow their steps until Python is installed.
Make sure to allow Python to be added to your environment variables, so it’s executable via terminal.
Install Pieces CLI
Once Python is installed, its dependency pip is automatically installed. We will use this to install Pieces CLI.
Open a terminal on your device and type pip install pieces-cli, or if you prefer to use Conda, type conda install pieces-cli. As long as Python is set up correctly, Pieces CLI will install.
If you’re on macOS, you can optionally install Pieces CLI via Homebrew:
homebrew install pieces-cli
Verify Installation
To verify a successful installation of the Pieces CLI, you can type pieces version within your terminal. This will display your Pieces OS and Pieces CLI versions.
If you receive 'pieces' is not recognized as an internal or external command, you can run pieces with py -m pieces $command.
Run Pieces CLI
To run Pieces CLI, you can enter the command pieces run. This will launch you into the Pieces CLI and make it so you don’t have to prefix with pieces.
Setting Up PiecesOS
To use the Pieces CLI, you must install PiecesOS on your working environment.
Click the download buttons or follow the set-up instructions below for your operating system:
macOS 13.0 (Ventura) or higher
macOS 13.0 (Ventura) or higher
Windows 10 (20H0) or higher required
Ubuntu 22.04+ required.
Run these commands in order to install and properly set up the Pieces Desktop App and it’s core dependencies:
-
sudo snap install pieces-os -
sudo snap connect pieces-os:process-control :process-control
Then, type pieces-os to launch the application directly from your terminal.
Click here for alternative PiecesOS installation methods, or install the PiecesOS and the Pieces Desktop App together for Windows, macOS, and Linux.
For enhanced security and better system integration, we recommend installing the .appinstaller package over the .exe installer. The .appinstaller package operates in a containerized environment, providing additional security benefits.
Updating
Follow the steps below to update the Pieces CLI.
Open a Terminal
Opening a terminal on your device depends on your platform: Open your OS’ search bar and enter terminal (macOS/Linux) or CMD (Windows).
Update Pieces CLI
In the open terminal, type pip install pieces-cli -U. This will update Pieces CLI with no other interaction needed. If you’re using Conda, type conda update pieces-cli to update Pieces CLI.
On Linux or macOS, running the command with sudo permissions may be required. To do this, run sudo pip install pieces-cli -U.
Onboarding
The Pieces CLI offers a walkthrough to guide you through the steps of saving your first material and introduces you to the Long-Term Memory Engine (LTM-2), enabling you to make the most of the Pieces CLI.
Save Your First Material
The onboarding will start by providing you with a snippet to copy to your clipboard. Highlight the code and press ⌘+c (macOS) or ctrl+c (Windows/Linux).
After copying the snippet, you can select any key on your keyboard to proceed.
If you haven’t copied the snippet, Pieces won’t allow you to paste.
After pressing any key, Pieces will prompt you to type pieces create into your terminal. With the snippet still copied, enter pieces create, and Pieces will ask if you want to save the snippet.
Type y and press return(macOS) or enter(Windows/Linux) to confirm to save the snippet to your Pieces Drive.
Finding your Saved Materials
In this step, you'll learn how to open your saved materials. Start by typing pieces list in your terminal and pressing enter.
This will display a list of all your saved materials. You can navigate through them using the arrow keys on your keyboard.
Select the material you're highlighting by pressing return(macOS) or enter(Windows/Linux).
Start a Session
After selecting a snippet, Pieces CLI will boot you out to the terminal to prompt you to start a new session.
Typing pieces run will open a new session, allowing you to enter Pieces commands without prefixing with pieces.
After the session, you can type exit and press return(macOS) or enter(Windows/Linux) to return to the onboarding.
Chat with the Copilot
This section will walk you through how to ask Pieces Copilot its first question. You can begin in your terminal by typing pieces ask 'How to print I love Pieces CLI in Python and Java' and pressing return(macOS) or enter(Windows/Linux).
After typing your question and running the command, Pieces Copilot will quickly generate and display the best response for your query.
It will then prompt you to do it with the Pieces CLI running by typing pieces run entering the command and then entering ask $question, $question being the question you’d like to ask Pieces Copilot.
Your question must be encased in quotations or Pieces won’t capture your full question.
More Resources
Your feedback is vital to us. This onboarding step will prompt you to enter pieces feedback where you can optionally open the GitHub discussion board related to Pieces CLI to leave helpful feedback.
If you enter y it will open the GitHub discussion board in a new tab in your browser, otherwise it will skip this step.
After completing the feedback, Pieces will prompt you to type pieces contribute and then ask if you’d like to open the source code for Pieces CLI on GitHub to improve it. You can optionally say yes by entering y; otherwise, enter n.
Uninstalling
Follow the steps below to uninstall the Pieces CLI.
If you also want to uninstall PiecesOS, follow these steps.
Open a Terminal
Opening a terminal on your device depends on your platform: Open your OS’ search bar and enter terminal(macOS/Linux) or CMD(Windows).
Run Uninstall Command
If you installed Pieces CLI using PIP, you can type pip uninstall pieces-cli to remove the CLI. If you used Conda, you can type conda remove pieces-cli.
