{"id":28558111,"url":"https://github.com/pydio/cells-client","last_synced_at":"2025-06-10T08:07:35.220Z","repository":{"id":46167249,"uuid":"162443657","full_name":"pydio/cells-client","owner":"pydio","description":"Command line client to communicate with cells REST api.","archived":false,"fork":false,"pushed_at":"2025-06-06T08:52:07.000Z","size":1102,"stargazers_count":24,"open_issues_count":2,"forks_count":17,"subscribers_count":7,"default_branch":"main","last_synced_at":"2025-06-06T09:35:16.715Z","etag":null,"topics":["api-client","cells","pydio","rest-api"],"latest_commit_sha":null,"homepage":"https://pydio.com","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/pydio.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.html","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}},"created_at":"2018-12-19T13:46:09.000Z","updated_at":"2025-06-06T08:52:12.000Z","dependencies_parsed_at":"2023-12-07T16:29:17.197Z","dependency_job_id":"8df37666-f695-44f1-8e4f-0566696c1634","html_url":"https://github.com/pydio/cells-client","commit_stats":null,"previous_names":[],"tags_count":36,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pydio%2Fcells-client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pydio%2Fcells-client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pydio%2Fcells-client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pydio%2Fcells-client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/pydio","download_url":"https://codeload.github.com/pydio/cells-client/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/pydio%2Fcells-client/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":259033839,"owners_count":22795770,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["api-client","cells","pydio","rest-api"],"created_at":"2025-06-10T08:07:34.583Z","updated_at":"2025-06-10T08:07:35.206Z","avatar_url":"https://github.com/pydio.png","language":"Go","readme":"\u003cimg src=\"https://github.com/pydio/cells/wiki/images/PydioCellsColor.png\" width=\"400\"  alt=\"Pydio Cells Logo\"/\u003e\n\n[Homepage](https://pydio.com/) | [GitHub-Repository](https://github.com/pydio/cells-client) |\n[Issue-Tracker](https://github.com/pydio/cells-client/issues)\n\n[![License Badge](https://img.shields.io/badge/License-Apache2-blue.svg)](LICENSE)\n[![Go Report Card](https://goreportcard.com/badge/github.com/pydio/cells-client?rand=2)](https://goreportcard.com/report/github.com/pydio/cells-client)\n\nCells Client provides an easy way to communicate with a [Pydio Cells](https://github.com/pydio/cells) server instance from the command line (or from automation scripts). It uses the [Cells SDK for Go](https://github.com/pydio/cells-sdk-go) and the REST API under the hood.\n\nCells Client a.k.a. `cec` works like standard command line tools like **ls**, **scp**, etc.  Using the `cec` command, you can list, download and upload directly to your remote Cells server.\n\nThe v4 version of this tool is meant to be used with a remote Cells server that is also at version v4+, please rather use cells-client v2 if your server is older (but you really should update your Cells server!).\n\n## Usage\n\n**Use the `cec --help` command** to learn about all available commands: the in-line doc is pretty complete.   \nYou can also find the [complete documentation for each command on our website](https://pydio.com/en/docs/developer-guide/cells-client-cec).\n\nSome useful commands for manipulating files:\n\n- `cec ls`: List files and folders on the server, when no path is provided, it lists the workspaces that the current user can access.\n- `cec scp`: Upload/Download file to/from a remote server.\n- `cec cp`, `cec mv` and `cec rm`: Copy, move, rename and delete files **within the server**.\n- `cec mkdir`: Create a folder on the remote server\n- `cec clear`: Clear authentication tokens stored in your keychain.\n\nA few examples (assuming that your client is connected to a server - see the [Section below](#connecting-to-cells) for connecting):\n\n### 1/ Listing the content of the personal-files workspace\n\n```sh\n$ cec ls personal-files\n+--------+--------------------------+\n|  TYPE  |           NAME           |\n+--------+--------------------------+\n| Folder | personal-files           |\n....\n| Folder | recycle_bin              |\n| File   | test_crud-1545206846.txt |\n| File   | test_file2.txt           |\n+--------+--------------------------+\n```\n\n### 2/ Showing details about a file\n\n```sh\n$ cec ls personal-files/P5021040.jpg -d\nListing: 1 results for personal-files/P5021040.jpg\n+------+--------------------------------------+-----------------------------+--------+------------+\n| TYPE |                 UUID                 |            NAME             |  SIZE  |  MODIFIED  |\n+------+--------------------------------------+-----------------------------+--------+------------+\n| File | 98bbd86c-acb9-4b56-a6f3-837609155ba6 | personal-files/P5021040.jpg | 3.1 MB | 5 days ago |\n+------+--------------------------------------+-----------------------------+--------+------------+\n```\n\n### 3/ Uploading a file to server\n\n```sh\n$ cec scp ./README.md cells://common-files/\nCopying ./README.md to cells://common-files/\n ## Waiting for file to be indexed...\n ## File correctly indexed\n```\n\n### 4/ Download a file from server\n\n```sh\n$ cec scp cells://personal-files/IMG_9723.JPG ./\nCopying cells://personal-files/IMG_9723.JPG to ./\nWritten 822601 bytes to file\n```\n\n## Installation\n\nCells Client is a single self-contained binary file and is easy to install.\n\n### 1 - Download cec\n\nGrab the built version for your corresponding amd64 architectures:\n\n- [Linux](https://download.pydio.com/latest/cells-client/release/{latest}/linux-amd64/cec)\n- [MacOS](https://download.pydio.com/latest/cells-client/release/{latest}/darwin-amd64/cec)\n- [Windows](https://download.pydio.com/latest/cells-client/release/{latest}/windows-amd64/cec.exe)\n\n### 2 - Make it executable\n\nGive execution permissions to the binary file, typically on Linux: `chmod u+x cec`.\n\n### 3 - Add it to the PATH (optional)\n\nAdd the command to your `PATH` environment variable, to makes it easy to call the command from anywhere in the system. On Linux, you can for instance add a symlink to the binary location (replace below with correct path):\n\n```sh\nsudo ln -s /path/to/your/binary/cec /usr/local/bin/cec\n```\n\n### 4 - Check for correct installation\n\nTo verify that `cec` is correctly installed, simply run for instance:\n\n```sh\n$ cec version\n# Should output something like below\nCells Client\n Version: \t    4.0.0\n Git commit: \tf8ad2c9b23977e344da6fa241a297926b697d71c\n Timestamp: \t2023-10-11T17:09:07Z\n OS/Arch: \t    linux/amd64\n Go version: \tgo1.21.3\n```\n\n## Connecting To Cells\n\nCells Client requires an authenticated connection to the target Cells server. For a given user, read/write permissions are applied in the same way as what you see in the web interface.\n\nOnce a valid user is available, there are 2 options:\n\n- Go through an interactive configuration and persist necessary information on the client machine (Persistent Mode)\n- Pass the necessary connection information at each call (Non-Persistent Mode)\n\n### Persistent Mode\n\nConnections can be configured and persisted locally on the client machine. As from version **v2.2.0**, you can [configure multiple _accounts_ on the client side and switch between them as necessary](https://github.com/pydio/build-cells/blob/407c3127961b3334a5223c85e3f5411df7105372/release/changelogs/cells-client-v2.2.0.md).  \nLast used connection is persisted locally in the main configuration file and will be re-used the next time you call the `cec` command.\n\nTo switch between accounts, simply call `cec config use`. \n\nCalling the `cec config add` command offers various authentication mechanisms. For persistent mode, we advise to use the default OAuth _Authorization Code_ flow.\n\n```sh\ncec config add oauth\n```\n\nYou will be guided through a few steps to configure and persist your connection:\n\n- Enter your server address: the full URL to access your Cells instance, e.g.: `https://files.example.com/`\n- Choose OAuth2 process either by opening a browser or copy/pasting the URL in your browser to get a valid token\n- Test and validate the connection.\n\nThe token is saved locally and will be refreshed automatically as required. If a keyring mechanism is available on the machine, it is used to store sensitive information. You can verify this with the following command:\n\n```sh\ncec config check-keyring \n```\n\nSupported keyring systems are MacOSX Keychain, Linux DBUS and Windows Credential Manager API.\n\n#### Troubleshooting\n\nWhen launching the Cells Client, following error is thrown:\n\n```sh\n2022/10/14 17:33:07 unexpected error during initialisation phase: exec: \"dbus-launch\": executable file not found in $PATH\n```\n\nThis mostly happens when Cells Client cannot find the keyring it expects to store credentials. Under Debian/Ubuntu Linux, you can install necessary software with (even if you do not use GNOME):\n\n```sh \nsudo apt install dbus-launch libpam-gnome-keyring gnome-keyring-pkcs11\n```\n\n### Non Persistent Mode\n\nThis mode can be useful to use the Cells Client in a CI/CD pipe or via cron jobs. In such case, we strongly advise you to create a _Personal Access Token_ on the server and use this.\n\nTo create a token that is valid for user `robot` for 90 days, log via SSH into your server as `pydio` (a.k.a. as the user that **runs** the `cells` service) and execute:\n\n```sh\n$ cells admin user token -u robot -e 90d\n✔ This token for robot will expire on Tuesday, 01-Jun-21 16:46:40 CEST.\n✔ d-_-x3N8jg9VYegwf5KpKFTlYnQIzCrvbXHzS24uB7k.mibFBN2bGy3TUVzJvcrnUlI9UuM3-kzB1OekrPLLd4U\n⚠ Make sure to secure it as it grants access to the user resources!\n```\n\nNote: if you have the Enterprise Edition, you can also manage Personal Access Token via the web GUI:\n\n- Go to `Cells Admin Console \u003e\u003e Identity Management \u003e\u003e People`\n- Edit the user you want to create a token for\n- Go to the `Personal Access Token` page.\n\nThen use environment variables (or the corresponding command flags) to pass connection information:\n\n```sh\nexport CEC_URL=https://files.example.com\nexport CEC_TOKEN=d-_-x3N8jg9VYegwf5KpKFTlYnQIzCrvbXHzS24uB7k.mibFBN2bGy3TUVzJvcrnUlI9UuM3-kzB1OekrPLLd4U\n```\n\nYou can now directly talk to your server, for instance:\n\n```sh\ncec ls common-files \n```\n\n\u003e Note that environment variables take the precedence as soon as you have the `CEC_URL` variable defined. In such case please insure you have the necessary variables defined depending on your target authentication mode. \n\n## Command Completion\n\nCells Client provides a handy feature that provides completion on commands and paths; both on local and remote machines.\n\n_NOTE: you **must** add `cec` to you local `PATH` if you want to configure the completion helper (see above)._\n\n### Bash completion\n\nTo enable this feature, you must have `bash-completion` third party add-on installed on your workstation.\n\n```sh\n# on Debian / Ubuntu\nsudo apt install bash-completion\n\n# on RHEL / Rocky Linux\nsudo dnf install bash-completion\n\n# on MacOS (make sure to follow the instructions displayed by Homebrew)\nbrew install bash-completion\n```\n\n_MacOS latest release changed the default shell to ZSH_.\n\nThen, to add the completion in a persistent manner:\n\n```sh\n# Linux users\ncec completion bash | sudo tee /etc/bash_completion.d/cec\n# MacOS users \ncec completion bash | sudo tee /usr/local/etc/bash_completion.d/cec\n```\n\nYou can also only _source_ the file in current session, the feature will be gone when you start a new shell.\n\n```sh\nsource \u003c(cec completion bash)\n```\n\nNote: if you want to use completion for remote paths while using `scp` sub command, you have to prefix the _remote_ path with `cells//` rather than `cells://`; that is to omit the column character before the double slash. Typically:\n\n```sh\ncec scp ./README.md cells//com \u003cpress the tab key\u003e\n# Completes the path to\ncec scp ./README.md cells//common-files/\n...\n```\n\nNote: when you update the Cells Client, you also have to update the completion file, typically on Linux machines:\n\n```sh\ncec completion bash | sudo tee /etc/bash_completion.d/cec\nsource /etc/bash_completion.d/cec\n```\n\n## Build from source\n\nIf you rather want to directly compile the source code on your workstation, you require:\n\n- Go language 1.23 or higher, with a [correctly configured](https://golang.org/doc/install#testing) Go toolchain,\n- The necessary build utils (typically `make`, `gcc`, ...)\n- A git client\n\nYou can then retrieve the source code and use the `Makefile` to compile a binary for your OS:\n\n```sh\ngit clone https://github.com/pydio/cells-client.git\ncd ./cells-client\nmake dev\n```\n\nCells Client uses the Go Modules mechanism to manage dependencies: you can check out the code anywhere in your local machine, it does not have to be within your `GOPATH`.\n\n## License\n\nThis project is licensed under the Apache V2 License - see the LICENSE file for details.\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpydio%2Fcells-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpydio%2Fcells-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpydio%2Fcells-client/lists"}