{"id":15512090,"url":"https://github.com/pieces-app/cli-agent","last_synced_at":"2026-05-29T00:01:32.881Z","repository":{"id":212505466,"uuid":"731625798","full_name":"pieces-app/cli-agent","owner":"pieces-app","description":"Pieces CLI for interacting with Pieces OS","archived":false,"fork":false,"pushed_at":"2026-05-28T20:14:15.000Z","size":25457,"stargazers_count":106,"open_issues_count":71,"forks_count":40,"subscribers_count":1,"default_branch":"main","last_synced_at":"2026-05-28T21:22:17.144Z","etag":null,"topics":["ai","cli","pieces"],"latest_commit_sha":null,"homepage":"https://docs.pieces.app/products/cli","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pieces-app.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2023-12-14T13:58:14.000Z","updated_at":"2026-05-28T19:54:42.000Z","dependencies_parsed_at":"2023-12-20T21:34:05.634Z","dependency_job_id":"72788d34-8f60-4d61-a337-1e1ee97bb5bf","html_url":"https://github.com/pieces-app/cli-agent","commit_stats":null,"previous_names":["pieces-app/cli-agent"],"tags_count":237,"template":false,"template_full_name":null,"purl":"pkg:github/pieces-app/cli-agent","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pieces-app%2Fcli-agent","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pieces-app%2Fcli-agent/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pieces-app%2Fcli-agent/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pieces-app%2Fcli-agent/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pieces-app","download_url":"https://codeload.github.com/pieces-app/cli-agent/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pieces-app%2Fcli-agent/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":33630999,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-05-28T02:00:06.440Z","response_time":99,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["ai","cli","pieces"],"created_at":"2024-10-02T09:53:25.760Z","updated_at":"2026-05-29T00:01:32.860Z","avatar_url":"https://github.com/pieces-app.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"# Pieces Python CLI Tool\n\n\u003cp align=\"center\"\u003e 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\u003c/p\u003e\n  \n##### \u003cp align=\"center\"\u003e [Website](https://pieces.app/) • [PiecesOS Documentation](https://docs.pieces.app/) • [Pieces CLI Documentation](https://docs.pieces.app/extensions-plugins/cli)\n\u003c/p\u003e\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` -\u003e The index\n- `current asset` -\u003e The asset that you are currently using can be changed by the open command\n- `current conversation` -\u003e 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)\"' \u003e\u003e ~/.bashrc \u0026\u0026 source ~/.bashrc\n```\n\n- **Zsh:**\n```zsh\necho 'eval \"$(pieces completion zsh)\"' \u003e\u003e ~/.zshrc \u0026\u0026 source ~/.zshrc\n```\n\n- **Fish:**\n```fish\necho 'pieces completion fish | source' \u003e\u003e ~/.config/fish/config.fish \u0026\u0026 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 \u0026 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","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpieces-app%2Fcli-agent","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpieces-app%2Fcli-agent","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpieces-app%2Fcli-agent/lists"}