Pydio Cells client

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:

• MacOS
• Windows
• Linux

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)
• 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 and cec rm: Copy, move, rename and delete files within the server.
• cec mkdir: Create a folder on the remote server
• cec 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.