| Name | pieces-cli JSON |
| Version |
1.18.1
JSON |
| download |
| home_page | None |
| Summary | A powerful cli tool to interact with PiecesOS |
| upload_time | 2025-08-30 04:22:09 |
| maintainer | None |
| docs_url | None |
| author | Pieces |
| requires_python | <3.14,>=3.11 |
| license | MIT |
| keywords |
copilot
pieces
ai
snippets
materials
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Pieces Python CLI Tool
<p align="center"> This is a comprehensive command-line interface (CLI) tool designed to interact seamlessly with PiecesOS. It provides a range of functionalities such as asset management, application interaction, and integration with various PiecesOS features.
</p>
##### <p align="center"> [Website](https://pieces.app/) • [PiecesOS Documentation](https://docs.pieces.app/) • [Pieces CLI Documentation](https://docs.pieces.app/extensions-plugins/cli)
</p>
[](https://www.youtube.com/watch?v=kAgwHMxWY8c)
## Important
Make sure you have [**PiecesOS**](https://docs.pieces.app/products/meet-pieces/fundamentals) installed in order to run the Pieces CLI tool.
#### 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 PiecesOS is installed and running on your system.
2. Install the Python package:
```bash
pip install pieces-cli
```
```bash
brew install pieces-cli
```
```bash
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
## Shell Completion
The Pieces CLI supports auto-completion for bash, zsh, fish, and PowerShell. To enable completion for your shell, run:
```bash
pieces completion [shell]
```
**Quick setup commands for each shell:**
- **Bash:**
```bash
echo 'eval "$(pieces completion bash)"' >> ~/.bashrc && source ~/.bashrc
```
- **Zsh:**
```zsh
echo 'eval "$(pieces completion zsh)"' >> ~/.zshrc && source ~/.zshrc
```
- **Fish:**
```fish
echo 'pieces completion fish | source' >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish
```
- **PowerShell:**
```powershell
Add-Content $PROFILE '$completionPiecesScript = pieces completion powershell | Out-String; Invoke-Expression $completionPiecesScript'; . $PROFILE
```
After setup, restart your terminal or source your configuration file. Then try typing `pieces ` and press **Tab** to test auto-completion!
## Usage
To refer to the list of all the commands currently supported in the Pieces CLI Agent, visit the [documentation](https://docs.pieces.app/extensions-plugins/cli/commands).
## Contributing
### Installation
To run this project locally, follow these steps:
1. Fork this project via GitHub.
2. Clone this project:
```shell
git clone https://github.com/pieces-app/cli-agent
```
3. Create a Virtual Environment
```shell
python3 -m venv venv
```
4. Activate Your Virtualenv
```shell
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:
```shell
pip install poetry
```
6. Then use poetry to install the required dependencies
```shell
poetry install
```
7. You build with
```shell
poetry build
```
8. Finally any project dependencies should be added to the pyproject.toml file with
```shell
poetry add
```
9. Open the Dist folder
```shell
cd dist
```
10. Install the WHL file
```shell
pip install pieces-cli-{VERSION}-py3-none-any.whl
```
replace the VERSION with the version you downloaded
Note: Ensure you get latest from the [releases](https://github.com/pieces-app/cli-agent/releases) of the cli-agent
11. To view all the CLI Commands
```shell
pieces help
```
these can be local/github/pypi etc.
### Updating
To update the project, run the following command:
```shell
pip install pieces-cli --upgrade
```
### Testing
To discover and run all the test cases in the repository, run the following command:
```shell
pytest
```
To check the test coverage, you can use the coverage package. Install coverage with:
```shell
pip install coverage
```
Run the tests with coverage using the following command:
```shell
coverage run -m pytest
coverage report
```
### Uninstallation
To uninstall the project, run the following command:
```shell
pip uninstall pieces-cli
```
Don't forget to remove the virtual environment and dist folder
## Available Commands
```
run - Starts a looped version of the CLI that only requires you to type the flag
list - Lists all the materials in your Pieces Drive (alias: 'drive')
list apps - List all registered applications
list models - List all registered AI models and change the AI model that you are using the ask command
modify - Modify the current material content after you edit it in the editor
edit - Edit the current material name or classification you can use -n and -c for name and classification respectively
delete - Deletes the current or most recent material.
create - Creates a new material based on what you've copied to your clipboard
execute - Execute a Pieces bash material
clear - to clear the terminal
config - View current configuration
config --editor x - Set the editor to 'x' in the configuration
ask "ask" - Asks a single question to the model selected in change model. Default timeout set to 10 seconds
--materials,-m - Add material(s) by index. Separate materials with spaces. Run 'drive' to find material indexes
--file,-f - Add a certain files or folders to the ask command it can be absolute or relative path
chats - List all the chats. The green chat shows the currently using one in the ask command
chat - Show the messages of the currently using chat in the ask command
chat x - List all the messages in a certain chat and switch to it in the ask command
-n,--new - To create a new chat in the ask command
-d,--delete - Deletes the current chat
-r,--rename - Rename the current chat. If no value given it will let the model rename it for you
commit - Commits the changes to github and auto generate the message, you can use -p or --push to push
search q - Does a fuzzy search for your query
--mode ncs - Does a neural code search for your query
--mode fts - Does a full text search for your query
login - Login to pieces
logout - Logout from pieces
version - Gets version of PiecesOS and the version of the cli tool
help - Show this help message
onboarding - Start the onboarding process
feedback - Send feedback to Pieces
contribute - Contribute to Pieces CLI
install - Install PiecesOS
open - Opens PiecesOS
```
Raw data
{
"_id": null,
"home_page": null,
"name": "pieces-cli",
"maintainer": null,
"docs_url": null,
"requires_python": "<3.14,>=3.11",
"maintainer_email": null,
"keywords": "copilot, pieces, ai, snippets, materials",
"author": "Pieces",
"author_email": "development@pieces.app",
"download_url": "https://files.pythonhosted.org/packages/d2/d6/cd0820776a31535f0287b73ee7935cf2e889273c437ec630c1b7fe9bf776/pieces_cli-1.18.1.tar.gz",
"platform": null,
"description": "# Pieces Python CLI Tool\n\n<p align=\"center\"> This is a comprehensive command-line interface (CLI) tool designed to interact seamlessly with PiecesOS. It provides a range of functionalities such as asset management, application interaction, and integration with various PiecesOS features.\n\n</p>\n \n##### <p align=\"center\"> [Website](https://pieces.app/) \u2022 [PiecesOS Documentation](https://docs.pieces.app/) \u2022 [Pieces CLI Documentation](https://docs.pieces.app/extensions-plugins/cli)\n</p>\n\n[](https://www.youtube.com/watch?v=kAgwHMxWY8c)\n\n## Important\n\nMake sure you have [**PiecesOS**](https://docs.pieces.app/products/meet-pieces/fundamentals) installed in order to run the Pieces CLI tool.\n\n#### Operating System Support\n\nThe 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.\n\nThe CLI Supports\n\n- Windows 10 or greater\n- Mac\n- Windows\n\n## Installing\n\nTo get started with the Pieces Python CLI Tool, you need to:\n\n1. Ensure PiecesOS is installed and running on your system.\n2. Install the Python package:\n\n ```bash\n pip install pieces-cli\n ```\n\n ```bash\n brew install pieces-cli\n ```\n\n ```bash\n conda install pieces-cli\n ```\n\n## Getting Started\n\nAfter 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.\n\n### Some important terminologies\n\n- `x` -> The index\n- `current asset` -> The asset that you are currently using can be changed by the open command\n- `current conversation` -> The conversation that you currently using in the ask command\n\n## Shell Completion\n\nThe Pieces CLI supports auto-completion for bash, zsh, fish, and PowerShell. To enable completion for your shell, run:\n\n```bash\npieces completion [shell]\n```\n\n**Quick setup commands for each shell:**\n\n- **Bash:**\n```bash\necho 'eval \"$(pieces completion bash)\"' >> ~/.bashrc && source ~/.bashrc\n```\n\n- **Zsh:**\n```zsh\necho 'eval \"$(pieces completion zsh)\"' >> ~/.zshrc && source ~/.zshrc\n```\n\n- **Fish:**\n```fish\necho 'pieces completion fish | source' >> ~/.config/fish/config.fish && source ~/.config/fish/config.fish\n```\n\n- **PowerShell:**\n```powershell\nAdd-Content $PROFILE '$completionPiecesScript = pieces completion powershell | Out-String; Invoke-Expression $completionPiecesScript'; . $PROFILE\n```\n\nAfter setup, restart your terminal or source your configuration file. Then try typing `pieces ` and press **Tab** to test auto-completion!\n\n## Usage\n\nTo refer to the list of all the commands currently supported in the Pieces CLI Agent, visit the [documentation](https://docs.pieces.app/extensions-plugins/cli/commands).\n\n## Contributing\n\n### Installation\n\nTo run this project locally, follow these steps:\n\n1. Fork this project via GitHub.\n\n2. Clone this project:\n\n```shell\ngit clone https://github.com/pieces-app/cli-agent\n```\n\n3. Create a Virtual Environment\n\n```shell\npython3 -m venv venv\n```\n\n4. Activate Your Virtualenv\n\n```shell\nsource venv/bin/activate for Mac & Linux OS\n\ncd venv\\Scripts for Windows OS\nactivate\n```\n\n5. This project uses poetry for managing dependencies and builds. Install poetry with:\n\n```shell\npip install poetry\n```\n\n6. Then use poetry to install the required dependencies\n\n```shell\npoetry install\n```\n\n7. You build with\n\n```shell\npoetry build\n```\n\n8. Finally any project dependencies should be added to the pyproject.toml file with\n\n```shell\npoetry add\n```\n\n9. Open the Dist folder\n\n```shell\ncd dist\n```\n\n10. Install the WHL file\n\n```shell\npip install pieces-cli-{VERSION}-py3-none-any.whl\n```\n\nreplace the VERSION with the version you downloaded\nNote: Ensure you get latest from the [releases](https://github.com/pieces-app/cli-agent/releases) of the cli-agent\n\n11. To view all the CLI Commands\n\n```shell\npieces help\n```\n\nthese can be local/github/pypi etc.\n\n### Updating\n\nTo update the project, run the following command:\n\n```shell\npip install pieces-cli --upgrade\n```\n\n### Testing\n\nTo discover and run all the test cases in the repository, run the following command:\n\n```shell\npytest\n```\n\nTo check the test coverage, you can use the coverage package. Install coverage with:\n\n```shell\npip install coverage\n```\n\nRun the tests with coverage using the following command:\n\n```shell\ncoverage run -m pytest\ncoverage report\n```\n\n### Uninstallation\n\nTo uninstall the project, run the following command:\n\n```shell\npip uninstall pieces-cli\n```\n\nDon't forget to remove the virtual environment and dist folder\n\n## Available Commands\n\n```\n run - Starts a looped version of the CLI that only requires you to type the flag\n\n list - Lists all the materials in your Pieces Drive (alias: 'drive')\n list apps - List all registered applications\n list models - List all registered AI models and change the AI model that you are using the ask command\n\n modify - Modify the current material content after you edit it in the editor\n edit - Edit the current material name or classification you can use -n and -c for name and classification respectively\n delete - Deletes the current or most recent material.\n create - Creates a new material based on what you've copied to your clipboard\n execute - Execute a Pieces bash material\n clear - to clear the terminal\n\n config - View current configuration\n config --editor x - Set the editor to 'x' in the configuration\n\n ask \"ask\" - Asks a single question to the model selected in change model. Default timeout set to 10 seconds\n --materials,-m - Add material(s) by index. Separate materials with spaces. Run 'drive' to find material indexes\n --file,-f - Add a certain files or folders to the ask command it can be absolute or relative path\n\n chats - List all the chats. The green chat shows the currently using one in the ask command\n chat - Show the messages of the currently using chat in the ask command\n chat x - List all the messages in a certain chat and switch to it in the ask command\n -n,--new - To create a new chat in the ask command\n -d,--delete - Deletes the current chat\n -r,--rename - Rename the current chat. If no value given it will let the model rename it for you\n\n commit - Commits the changes to github and auto generate the message, you can use -p or --push to push\n\n search q - Does a fuzzy search for your query\n --mode ncs - Does a neural code search for your query\n --mode fts - Does a full text search for your query\n\n login - Login to pieces\n logout - Logout from pieces\n\n version - Gets version of PiecesOS and the version of the cli tool\n help - Show this help message\n onboarding - Start the onboarding process\n feedback - Send feedback to Pieces\n contribute - Contribute to Pieces CLI\n install - Install PiecesOS\n open - Opens PiecesOS\n```\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "A powerful cli tool to interact with PiecesOS ",
"version": "1.18.1",
"project_urls": {
"Homepage": "https://pieces.app",
"Repository": "https://github.com/pieces-app/cli-agent"
},
"split_keywords": [
"copilot",
" pieces",
" ai",
" snippets",
" materials"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "2e55b577a0df0ba83c9c9395824476e01d76bf805ab478e681e5fc8b7ce56f25",
"md5": "bf4c6adc8d871883c6827dfd53df5f8f",
"sha256": "4f5a885702406d670e8be95830eb1e4d7df1f365cc915ad9b93263e0280a1f39"
},
"downloads": -1,
"filename": "pieces_cli-1.18.1-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bf4c6adc8d871883c6827dfd53df5f8f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<3.14,>=3.11",
"size": 1489196,
"upload_time": "2025-08-30T04:22:07",
"upload_time_iso_8601": "2025-08-30T04:22:07.795767Z",
"url": "https://files.pythonhosted.org/packages/2e/55/b577a0df0ba83c9c9395824476e01d76bf805ab478e681e5fc8b7ce56f25/pieces_cli-1.18.1-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "d2d6cd0820776a31535f0287b73ee7935cf2e889273c437ec630c1b7fe9bf776",
"md5": "cf068bbf1a0152e2f2146b299cf2bc51",
"sha256": "65c88a001a096e848cae8bacac9b06d6e26b6e11a5657220e9b8b26100636517"
},
"downloads": -1,
"filename": "pieces_cli-1.18.1.tar.gz",
"has_sig": false,
"md5_digest": "cf068bbf1a0152e2f2146b299cf2bc51",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<3.14,>=3.11",
"size": 537980,
"upload_time": "2025-08-30T04:22:09",
"upload_time_iso_8601": "2025-08-30T04:22:09.627828Z",
"url": "https://files.pythonhosted.org/packages/d2/d6/cd0820776a31535f0287b73ee7935cf2e889273c437ec630c1b7fe9bf776/pieces_cli-1.18.1.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-30 04:22:09",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pieces-app",
"github_project": "cli-agent",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "pieces-cli"
}
