README.md

Pieces Python CLI Tool

This is a comprehensive command-line interface (CLI) tool designed to interact seamlessly with Pieces OS. It provides a range of functionalities such as asset management, application interaction, and integration with various Pieces OS features.

Website • Pieces OS Documentation • Pieces Python CLI Documentation

Table of Contents

• Operating System Support
• Installing
• Getting Started
• Terminologies
• Usage
  • Run
  • List (assets,apps,models)
  • Open, Save, Create, Edit, and Delete Assets
  • Search and Query
  • Change the model
  • conversations/conversation
  • Change Model
  • Ask a Question
  • login and logout
  • Additional Commands
• Supported Versions

Operating System Support

The Pieces Python CLI Tool is compatible with various operating systems, ensuring a wide range of usage and adaptability. While it offers full support across most systems, specific features might have varied performance based on the OS environment.

The CLI Supports

• Windows 10 or greater
• Mac
• Windows

Installing

To get started with the Pieces Python CLI Tool, you need to:

1. Ensure Pieces OS is installed and running on your system.

2. Install the Python package:

   pip install pieces-cli

   brew install pieces-cli

   conda install pieces-cli

Getting Started

After installing the CLI tool, you can access its functionalities through the terminal. The tool is initialized with the command pieces followed by various subcommands and options.

Some important terminologies

• x -> The index
• current asset -> The asset that you are currently using can be changed by the open command
• current conversation -> The conversation that you currently using in the ask command

Usage

Run

The run command starts the CLI in a loop. While you can use each command without running the CLI in a loop you'll get much faster results and a better experience using run.

Once the CLI is running in a loop you can simply type the command.

For instance: 
open

Instead of: 
pieces open

If you have a numbered list or search open you can just type the number and it will open the asset associated.

  pieces run

List command

To list assets applications or models, use the command:

Default of 10 assets

pieces list

Lists your x most recent assets

pieces list assets x

Lists all registered applications

pieces list apps

Lists all accessible AI models

pieces list models

Open an asset:

Opens an asset from a list or search. If only "open" is used then it will open your most recent asset. This also creates a link to the asset's code.

pieces open [ITEM_INDEX]

Save, Create, Edit, and Delete Assets

The save create edit and delete commands currrently work on the current asset which is by defualt set to the most recent one and you can change the current asset to anything using the open command above.

Save the current asset:

You need to edit the snippet code that was opened via the open command pieces open then save the changes to using the save command

pieces save

Create a new asset:

Will take whatever text is copied to your clipboard and create an asset. The asset will automatically be scanned and recognized for it's file type.

pieces create

Edit an existing asset:

This will edit the name and reclassify the current asset.

pieces edit

This is used to edit both the classification and name of an asset.

pieces edit --name "new name"

to edit the name

pieces edit --classification python

to edit the classification

You can you -n or -c to change the name and classification respectively with the edit command.

Delete an asset:

This will delete an opened asset by using list or search first. If you do not have an opened asset it will open your most recent asset and ask if you'd like to delete it.

pieces delete

Search and Query

Perform a fuzzy search:

pieces search [your query]

Finds strings that approximately match patterns. Normal search.

Perform a Neural Code Search:

pieces search query --mode ncs

Uses machine learning, deep neural networks, and natural language processing. It can understand the intent of a user's search query and match it with the most relevant results.

Perform a Full Text Search:

pieces search query --mode fts

Examines all words in a document to find matches to search criteria.

change the llm model you are using:

Change the model in the ask command.

pieces change_model [MODEL_INDEX]

Conversations command

Coversations

List all conversations that you have. The green conversation is the one that is currently being used in the ask command

pieces conversations

Conversation

List the messages in the currently using conversation in the ask command.

pieces conversation

You can create a new conversation that will be used in the ask command.

pieces conversation -n

Rename a conversation

pieces conversation -r My awsome name

Or you can make the model rename it for you

pieces conversation -r

Delete a conversation

pieces conversation -d

You can switch the conversation and list its messages. Check the conversations command to get the index

pieces conversation x

Ask a question to a model:

Requires quotes around question

Ask the Pieces Copilot a question. You can add a relevant file, you can also add relevant snippets based on their index shown in the assets list command. In order to change models from the default (GPT3.5), use the change_model command You can add a relevance file or snippet index check the list assets command. You can use . or / to refer to the current directory

pieces ask "your question" -f /file1 /file2 folder -s 1 2 3

Commiting to github

Auto commit the code to github and generate a commit message you can use the -p or --push flags to push the code to the repo too

pieces commit -p

Login and logout

Login to pieces

pieces login

Logout from pieces

pieces logout

Additional Commands

Retrieve the version of Pieces OS and the CLI:

pieces version

For a detailed help menu:

pieces help

Supported Versions

• Windows 10 or Greater
• Mac (insert later)
• Linux (insert later)

It is advised to keep the CLI tool updated to the latest version to ensure compatibility with Pieces OS and access to all features. Please refer to our documentation for details on supported versions.

Contributing

Installation

To run this project locally, follow these steps:

1. Fork this project via GitHub.

2. Clone this project:

git clone https://github.com/pieces-app/cli-agent

3. Create a Virtual Environment

python3 -m venv venv

4. Activate Your Virtualenv

source venv/bin/activate for Mac & Linux OS

cd venv\Scripts for Windows OS
activate 

5. This project uses poetry for managing dependencies and builds. Install poetry with:

pip install poetry

6. Then use poetry to install the required dependencies

poetry install

7. You build with

poetry build

8. Finally any project dependencies should be added to the pyproject.toml file with

poetry add 

9. Open the Dist folder

cd dist

10. Install the WHL file

pip install pieces-{VERSION}-py3-none-any.whl 

replace the VERSION with the version you downloaded Note: Ensure you get latest from the releases of the cli-agent

11. To view all the CLI Commands

pieces help 

these can be local/github/pypi etc.

Updating

To update the project, run the following command:

pip install pieces --upgrade

Uninstallation

To uninstall the project, run the following command:

pip uninstall pieces

Don't forget to remove the virtual environment and dist folder