pieces-cli


Namepieces-cli JSON
Version 1.16.5 PyPI version JSON
download
home_pageNone
SummaryA powerful cli tool to interact with PiecesOS
upload_time2025-07-14 14:47:11
maintainerNone
docs_urlNone
authorPieces
requires_python<3.14,>=3.11
licenseMIT
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>

[![Introducing CLI](https://img.youtube.com/vi/kAgwHMxWY8c/0.jpg)](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/67/26/3e8bde03fd92455652e059e0d7d7b8a7f2341cee808b98d9a6fc018c4b6b/pieces_cli-1.16.5.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[![Introducing CLI](https://img.youtube.com/vi/kAgwHMxWY8c/0.jpg)](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.16.5",
    "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": "a40d82189f15cc3385704f212a8499240459c27f3698a19a54c01a933773bab3",
                "md5": "f39dc4873c9f36c5606fbaac2f427f16",
                "sha256": "e2968219389ab744e05edcd13e573686cb0f1a02a50d2386b6b83ad8c6ed62b2"
            },
            "downloads": -1,
            "filename": "pieces_cli-1.16.5-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "f39dc4873c9f36c5606fbaac2f427f16",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": "<3.14,>=3.11",
            "size": 1388996,
            "upload_time": "2025-07-14T14:47:10",
            "upload_time_iso_8601": "2025-07-14T14:47:10.414291Z",
            "url": "https://files.pythonhosted.org/packages/a4/0d/82189f15cc3385704f212a8499240459c27f3698a19a54c01a933773bab3/pieces_cli-1.16.5-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": null,
            "digests": {
                "blake2b_256": "67263e8bde03fd92455652e059e0d7d7b8a7f2341cee808b98d9a6fc018c4b6b",
                "md5": "1f35bcb0279d67638ca109f5e6d53b4f",
                "sha256": "540d2f08f69f7f1729d679ae384d76b617850a3b8ad41d79b7f3733669aa1ec1"
            },
            "downloads": -1,
            "filename": "pieces_cli-1.16.5.tar.gz",
            "has_sig": false,
            "md5_digest": "1f35bcb0279d67638ca109f5e6d53b4f",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": "<3.14,>=3.11",
            "size": 469058,
            "upload_time": "2025-07-14T14:47:11",
            "upload_time_iso_8601": "2025-07-14T14:47:11.676247Z",
            "url": "https://files.pythonhosted.org/packages/67/26/3e8bde03fd92455652e059e0d7d7b8a7f2341cee808b98d9a6fc018c4b6b/pieces_cli-1.16.5.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2025-07-14 14:47:11",
    "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"
}
        
Elapsed time: 2.19853s