Homepage, GitHub-Repository, Issue-Tracker
This command line client allows interacting with a Pydio Cells server via the command line. It uses the Cells SDK for Go and the REST API under the hood.
Download
We provide binaries for the following amd64 architectures:
Installation
We do not provide a packaged installer for the various OSs.
Yet, Cells Client is a single self-contained binary file and is easy to install.
Typically on Linux, you have to:
- Download the latest binary file from Pydio website,
- Make it executable:
chmod u+x cec
, - Put it in your path or add a symlink to the binary location, typically:
sudo ln -s /<path-to-bin>/cec /usr/local/bin/cec
This last step is required if you want to configure the completion helper (see below).
Otherwise, you can also do./cec ls
directly (in such case, adapt the suggested commands to run the examples).
You can verify that cec
is correctly installed and configured by launching any command, for instance:
cec version
Installing from source
If you want to install from source, you must have go version 1.12+ installed and configured on your machine and the necessary build utils (typically make
, gcc
, ...). You can then download the source code and use the Makefile to compile a binary for your OS:
git clone https://github.com/pydio/cells-client.git
cd ./cells-client
make dev
Note: Cells Client uses the Go Modules mechanism to manage dependencies, so you do not have to be in your GOPATH.
Configuration
This step is compulsory if you do not want to precise all configuration information each time you call the command, typically on your working station. It guides through a few steps to gather necessary information and store sensitive bits in your keyring if you have one configured and running on your machine.
Default authentication mechanism is a OAuth Authorization Code flow.
# simply call
cec configure
You are then prompted for the following information:
- Server Address: full URL to Cells, e.g.:
https://cells.yourdomain.com/
- Client ID / Client Secret: this is used by the OpenIDConnect service for authentication.
Note that since the v2.0, a default public client is registered by default, using the suggested default values should work out of the box:- Client ID:
cells-client
- Client Secret: (leave empty)
- Client ID:
- Then follow the OAuth2 process either by opening a browser or copy/pasting the URL in your browser to get a valid token.
- The token is automatically saved in your keychain. It will be refreshed as necessary.
Example:
Assuming that I have a Pydio Cells instance running under this URL https://cells.my-files.com
and that I am running the command on the same graphical environment.
$ cec configure
Server Address (provide a valid URL): https://cells.my-files.com
✔ No
OAuth APP ID (found in your server pydio.json): cells-client
OAuth APP Secret (leave empty for a public client):
✔ Yes
Opening URL https://cells.my-files.com/oidc/oauth2/auth?client_id=cells-client&redirect_uri=http%3A%2F%2Flocalhost%3A3000%2Fservers%2Fcallback&response_type=code&state=XVlBzgbaiCMRAjWw
Now exchanging the code for a valid IdToken
✔Successfully Received Token!
⚠ Testing this configuration before saving
✔ Successfully logged to server, token will be refreshed at 2019-12-09 12:42:58 +0100 CET
✔ Configuration saved, you can now use the client to interract with https://cells.my-files.com.
If you have no tab opening in your browser you can manually copy the URL and put it in your browser
Command completion
Cells Client provides a handy feature that provides completion on commands and paths; both on local and remote machines.
To enable this feature, you must have bash-completion
third party add-on installed on your workstation.
# on Debian / Ubuntu
sudo apt install bash-completion
# on RHEL / CentOS
sudo yum install bash-completion
# on MacOS (make sure to follow the instructions displayed by Homebrew)
brew install bash-completion
MacOS users should update their bash version to v5, (by default it is using v3)
Then, to add the completion in a persistent manner:
# Linux users
cec completion bash, sudo tee /etc/bash_completion.d/cec
# MacOS users
cec completion bash, sudo tee /usr/local/etc/bash_completion.d/cec
You can also only source the file in current session, the feature will be gone when you start a new shell.
source <(cec completion bash)
Note: 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:
cec scp ./README.md cells//com <press the tab key>
# Completes the path to
cec scp ./README.md cells//common-files/
...
Note: when you update the Cells Client, you also have to update the completion file, typically on Linux machines:
cec completion bash, sudo tee /etc/bash_completion.d/cec
source /etc/bash_completion.d/cec
Usage
Use the cec --help
command to know about available commands. Below are a few interresting ones for manipulating files:
cec ls
: List files and folders on the server, when no path is provided, it lists the workspaces that the current user can access.cec scp
: Upload/Download file to/from a remote server.cec cp
,cec cp
andcec rm
: Copy, move, rename and delete files within the server.cec mkdir
: Create a folder on the remote servercec clear
: Clear authentication tokens stored in your keychain.
For your convenience, below are a few examples.
1/ Listing the content of the personal-files workspace
$ cec ls personal-files
+--------+--------------------------+, TYPE, NAME, +--------+--------------------------+, Folder, personal-files, File, Huge Photo-1.jpg, File, Huge Photo.jpg, File, IMG_9723.JPG, File, P5021040.jpg, Folder, UPLOAD, File, anothercopy, File, cec22, Folder, recycle_bin, File, test_crud-1545206681.txt, File, test_crud-1545206846.txt, File, test_file2.txt, +--------+--------------------------+
2/ Showing details about a file
$ cec ls personal-files/P5021040.jpg -d
Listing: 1 results for personal-files/P5021040.jpg
+------+--------------------------------------+-----------------------------+--------+------------+, TYPE, UUID, NAME, SIZE, MODIFIED, +------+--------------------------------------+-----------------------------+--------+------------+, File, 98bbd86c-acb9-4b56-a6f3-837609155ba6, personal-files/P5021040.jpg, 3.1 MB, 5 days ago, +------+--------------------------------------+-----------------------------+--------+------------+
3/ Uploading a file to server
$ cec scp ./README.md cells://common-files/
Copying ./README.md to cells://common-files/
## Waiting for file to be indexed...
## File correctly indexed
4/ Download a file from server
$ ./cec scp cells://personal-files/IMG_9723.JPG ./
Copying cells://personal-files/IMG_9723.JPG to ./
Written 822601 bytes to file
License
This project is licensed under the Apache V2 License - see the LICENSE file for details.