Solid-shell (Sol)

a command-line tool, batch processor, and interactive shell for managing Solid data

Solid-shell (hereafter called Sol) is a nodejs tool for accessing Solid data that may be run as an interactive shell, as a batch processor, and on the command line. It provides a front-end for Solid-File-Client and supports moving and copying files on remote pods, on local file systems, and between the two.

Here's an overview of methods :

     Document Management  put,post,patch get,head,options,copy,move,delete,recursiveDelete,zip,unzip
Testing/Batch Processing  run,exists,notExists,matchText,statusOnly,verbosity
            Connectivity  login, base
       Interactive Shell  shell, help, quit

Some recent changes :

There are now two methods to delete : simple delete (for a file or an empty folder) and recursiveDelete for an entire folder tree.
Added methods for patch and options
Added statusOnly to show e.g. 200 on a "get" rater than the full body

Installation

You can run without installing, with this command line: npx solid-shell shell.

If you want to instll, you can either install via npm or clone the github repo

To install with npm

  * npm install -g solid-shell
  * you should now be able to use "sol" to run solid-shell

To install via the github repo

On this page (https://github.com/jeff-zucker/solid-shell) press the code button in the upper right, copy the url presented
in your local console: git clone COPIED_URL
that should creaste a folder named solid-shell
in that folder use "./sol" to run solid-shell

Command-line usage

For one-off commands, you can run sol commands directly. For example this recursively uploads a folder to a Solid POD.

   sol --login copy ./someLocalPath/ /someRemotePath/

Enter sol -h to see a full list of commands available from the command line.

Interactive shell usage

You may also use sol as an interactive shell. Enter the shell like so:

sol shell

Once in the shell, enter "help" to see a list of commands available in the shell or "quit" to exit the interactive shell.

Logging in

You can read and write local resources and read public pod-based resources without logging in. To access private pod data, you will need to specify your login credentials and login. Sol looks for the credentials first in environment variables, and if not found, prompts you for them.

Prep for logging in with username/password on NSS

If using a Node-Solid-Server (NSS) such as solidcommunity.net you may login with username and password. This requires two one-time steps and which can thereafter be skipped:

Set https://solid-node-client as a trusted app for your pod by one of these methods:

a. manually edit your profile if you know how, or

b. go to your pod root e.g. https://YOU.solidcommunity.net/; login using the databrowser; click on the preferences tab; scroll to the bottom of the trusted apps and add https//solid-node-client
You can let Sol prompt you for login credentials each time, or you can set the following environment variables once and Sol will use them thereafter:

  SOLID_USERNAME
  SOLID_PASSWORD
  SOLID_IDP
  SOLID_REMOTE_BASE

See below "performing a login"

Prep for logging in with a token

If you are not using NSS or are not using the username/password login, please read the documentation for your server and find out how to get the data needed to set these environmen t variables. If these are not in your environment, you will be prompted for them when you login.

  SOLID_REFRESH_TOKEN
  SOLID_CLIENT_ID
  SOLID_CLIENT_SECRET
  SOLID_OIDC_ISSUER
  SOLID_REMOTE_BASE

Performing a login

You can invoke login from the command-line, in the interactive shell or from a script. In all cases Sol will look for the environment variables shown above and, if they any are missing, will prompt you for them.

From the command line :

  sol -l head /foo/private.txt
  sol --login head /foo/private.txt

Specifying a base folder

When you specify a base folder, it will be prepended to any URLs starting with /. In other words, if you set the base to "https://me.example.com/public" then a request "get /foo.ttl" will read https://me.example.com/public/foo.ttl.

You can set the Base in the environment variables shown above, or by using the base method in interactive or script mode.

Working with URLs

All methods in Solid-shell can use files or folders from local or remote locations. You must specify these options in the URL.

Folder URLs always end with a slash.

   https://me.example.com/foo/   a folder
   https://me.example.com/foo    a file

Absolute URLs start with https:// or file://

   https://me.exmaple.com/foo/bar.ttl   a remote file
   file:///home/me/foo/bar.ttl          a local file

Relative URLs start with ./ or /

   ./foo/bar.ttl  a local file relative to your current working folder
   /foo/bar.ttl   a remote file relative to your specified base folder

Methods

put <URL> <content>

Create a file or folder with Write permission. If the parent path does not exist, it will be created. E.g. if you don't have a /foo folder, "put /foo/bar.txt" will create /foo and /foo/bar.txt. For files, a put will over-write any existing file of the same name. For folders, if the folder pre-exists, put will keep the existing folder rather than overwrite it or create a new one.

For files, the URL should contain an extension that clearly labels the content-type e.g. .ttl for turtle, .txt for text, etc.

Content may be omitted to create a blank file.

Use of put requires Write permissions on the resource - if you have Append, but not Write permissions, use post instead.

post <URL> <content>

Ceate a file or folder with Append permission. Post works exactly the same as put with these exceptions :

It can be used with only Append permissions, it does not need full Write permission.
If the file or folder already exists, another version with a random prefix on the file name will be created, nothing will ever be overwritten

get <URL>

Read a file or folder and display its contents. Requires Read permission.

head <URL>

Show headers for a file or folder. Requires Read permission.

copy <URLa> <URLb>

Copy a file or recursively copy a folder. Needs Read permission on the fromp location and Write permission on the to location. Completely overwrites the to location if it exists.

move <URLa> <URLb>

Move a file or recursively move a folder. Needs Write permission on both the to and from locations . Completely overwrites the to location if it exists.

delete <URL>

Delete a file or recursively delete a folder. Needs Write permission on the resource.

zip <URL> <zipFile>

Create a zip archive. Needs Read permission on the URL and write permission on the zipFile location.

unzip <zipFile> <URL>

Extracts a zip archive. Needs Read permission on the zipFile location and Write permission on the extraction location.

Testing

You may test the existence of a resource with exists or notExists and the contents of a resource with matchText. See below for an example.

Batch Processing

You may put a series of Sol commands in a file and then run them as a batch either from the command-line or from the interactive shell.

From the command line:

  sol run ./myBatchFile

Within the batch file, commands should be separated by newlines; a line starting with # and will be treated as a comment; blank lines will be ignrored. Here's an example batch file: Here's an example of simple script which can be executed with "sol run ./script-name":

put ./test-folder/test.txt "hello world"
exists ./test-folder/test.txt
matchText  ./test-folder/test.txt "hello world"
delete ./test-folder/
notExists ./test-folder/
# END
Expected output :
  ok put <./test-folder/test.txt>
  ok exists <./test-folder/test.txt>
  ok contentsMatch <test.txt>
  ok delete <./test-folder/>
  ok notExists <./test-folder/>

See the scripts folder for more script examples.

jeff-zucker/solid-shell