From 7f117f4513216c31f701cf3dd76290079dc69af5 Mon Sep 17 00:00:00 2001 From: "Ruben D." Date: Wed, 8 Jan 2025 21:50:11 +0100 Subject: [PATCH] Documentation update --- .../markdown/documentation/cli/commands.md | 44 +- documentation/markdown/tutorial.md | 607 ++++------ documentation/site/404.html | 27 +- .../contributing/making-changes/index.html | 27 +- .../site/documentation/cli/access/index.html | 235 +++- .../site/documentation/cli/aliases/index.html | 29 +- .../cli/authentication/index.html | 723 ++++++++++- .../documentation/cli/commands/index.html | 73 +- .../documentation/cli/overview/index.html | 785 ------------ .../site/documentation/overview/index.html | 47 +- .../typescript/authentication/index.html | 27 +- .../typescript/css-specific/index.html | 27 +- .../typescript/example-requests/index.html | 27 +- .../typescript/metadata/index.html | 27 +- .../typescript/overview/index.html | 27 +- documentation/site/index.html | 45 +- documentation/site/search/search_index.json | 2 +- documentation/site/sitemap.xml | 30 +- documentation/site/sitemap.xml.gz | Bin 334 -> 331 bytes documentation/site/tutorial/index.html | 1070 +++++------------ package.json | 6 +- 21 files changed, 1521 insertions(+), 2364 deletions(-) delete mode 100644 documentation/site/documentation/cli/overview/index.html diff --git a/documentation/markdown/documentation/cli/commands.md b/documentation/markdown/documentation/cli/commands.md index 1d0a678..e7f671d 100644 --- a/documentation/markdown/documentation/cli/commands.md +++ b/documentation/markdown/documentation/cli/commands.md @@ -94,31 +94,32 @@ The `cp` command can copy resources between Solid pod locations, across Solid po If the source location is a container or directory, it will recursively copy the container and all sub-containers recursively copying the whole underlying resource tree, including empty containers. The default copying behavior ignores `.meta`, `.acl` and `.acp` resources, which can be changed using the `--all` flag. -The default behavior is to overwrite files, the `--interactive-override` and `--no-override` options provide alternative behaviors. +The copy command automatically copies the full recursive resource tree. At the moment this behavior cannot be altered. +In terms of overriding resources, the default setting is that every time a resource is found to already exist, an interactive prompt is shown. +This behavior can be altered either by the `--never-override` or the `--override` options. #### arguments ``` Arguments: - src file or directory to be copied - dst destination to copy file or directory to + src resource or container to be copied + dst destination to copy file or directory to ``` The `src` argument is the location of the resource or container to be moved. If the URL starts with `http(s)://`, the resource is assumed to be a remote resource, if not the resource is assumed to be local and matched with the local file system. The `dst` argument is the destination to which the source resource is to be copied. Similarly it uses the `http(s)://` prefix to decide if the location is local or remote. The default behavior ignores context resources such as `.meta`, `.acl` and `.acp` present in the directories. The `--all` flag ignores this behavior, though note that for authorization resources, as the target URIs are not edited, copying resources with these authorization resources does not imply they will result in the same access controls as the location they were copied from! -The default behavior always automatically works recursively. At the moment this behavior cannot be altered. #### options ``` Options: - -a, --all Copy .acl files in recursive directory copies - -i, --interactive-override Interactive confirmation prompt when overriding existing resource - -n, --no-override Do not override existing files - -v, --verbose Log all read and write operations + -a, --all Copy .acl files in recursive directory copies + -o, --override Automatically override existing files + -n, --never-override Automatically override existing files + -v, --verbose Log all read and write operations ``` The `--all` option includes `.meta`, `.acl` and `.acp` files in the listing.
-The `--interactive-override` option provides an interactive prompt when a copy will override an existing resource. +The `--override` option automatically overrides existing resources.
-The `--no-override` option ignores existing resources. +The `--never-override` option automatically mitigates resource overrides.
The `--verbose` option shows warnings. @@ -156,33 +157,32 @@ If the source location is a container or directory, it will recursively move the When moving from the local file system, files will not be deleted! The default copying behavior ignores `.meta`, `.acl` and `.acp` resources, which can be changed using the `--all` flag. -The default behavior is to overwrite files, the `--interactive-override` and `--no-override` options provide alternative behaviors. -The default behavior always automatically works recursively. At the moment this behavior cannot be altered. +The move command automatically moves the full recursive resource tree. At the moment this behavior cannot be altered. +In terms of overriding resources, the default setting is that every time a resource is found to already exist, an interactive prompt is shown. +This behavior can be altered either by the `--never-override` or the `--override` options. #### arguments ``` Arguments: - src file or directory to be moved - dst destination of the move + src resource or container to be moved + dst destination of the move ``` The `src` argument is the location of the resource or container to be moved. If the URL starts with `http(s)://`, the resource is assumed to be a remote resource, if not the resource is assumed to be local and matched with the local file system. The `dst` argument is the destination to which the source resource is to be copied. Similarly it uses the `http(s)://` prefix to decide if the location is local or remote. The default behavior ignores context resources such as `.meta`, `.acl` and `.acp` present in the directories. The `--all` flag ignores this behavior, though note that for authorization resources, as the target URIs are not edited, copying resources with these authorization resources does not imply they will result in the same access controls as the location they were copied from! - - #### options ``` Options: - -a, --all Move .acl files when moving directories recursively - -i, --interactive-override Interactive confirmation prompt when overriding existing files - -n, --no-override Do not override existing files - -v, --verbose Log all operations + -a, --all Copy .acl files in recursive directory copies + -o, --override Automatically override existing files + -n, --never-override Automatically override existing files + -v, --verbose Log all read and write operations ``` The `--all` option includes `.meta`, `.acl` and `.acp` files in the listing.
-The `--interactive-override` option provides an interactive prompt when a copy will override an existing resource. +The `--override` option automatically overrides existing resources.
-The `--no-override` option ignores existing resources. +The `--never-override` option automatically mitigates resource overrides.
The `--verbose` option shows warnings. diff --git a/documentation/markdown/tutorial.md b/documentation/markdown/tutorial.md index 86b303c..11a11b3 100644 --- a/documentation/markdown/tutorial.md +++ b/documentation/markdown/tutorial.md @@ -3,38 +3,6 @@ This tutorial provides a quick setup of a Community Solid Server, and some useful interactions to manage resources on a created Solid pod. -## Index -- [Bashlib Tutorial](#bashlib-tutorial) - - [Index](#index) - - [Setting up a Solid Server](#setting-up-a-solid-server) - - [Creating an account](#creating-an-account) - - [Setting up Bashlib](#setting-up-bashlib) - - [Bashlib-css](#bashlib-css) - - [Creating a new Solid account + data pod](#creating-a-new-solid-account--data-pod) - - [Creating a Client Credentials token](#creating-a-client-credentials-token) - - [Authentication options](#authentication-options) - - [Bashlib-solid](#bashlib-solid) - - [Authentication](#authentication) - - [Authenticate using Client Credentials token](#authenticate-using-client-credentials-token) - - [Interactive authentication](#interactive-authentication) - - [No authentication](#no-authentication) - - [Commands](#commands) - - [URL Prefixes](#url-prefixes) - - [fetch / cat](#fetch--cat) - - [list / ls](#list--ls) - - [copy / cp](#copy--cp) - - [move / mv](#move--mv) - - [remove / rm](#remove--rm) - - [mkdir](#mkdir) - - [touch](#touch) - - [find](#find) - - [query](#query) - - [perms](#perms) - - [edit](#edit) - - [Examples](#examples) - - [Creating a new pod and authentication token](#creating-a-new-pod-and-authentication-token) - - [Setting up a profile image on your pod](#setting-up-a-profile-image-on-your-pod) - ## Setting up a Solid Server To use Bashlib, we first explain how to setup your own local Solid Server on which you can create your first Solid pod. @@ -81,505 +49,350 @@ and associated WebID at `http://localhost:3000/mydatapod/profile/card#me`! ## Setting up Bashlib With our Solid pod and WebID created, now it is time to setup Bashlib! +For a quick setup, we use NPX ``` -git clone https://github.com/SolidLabResearch/Bashlib.git -cd Bashlib -bash setup.sh +npx solid-bashlib curl http://localhost:3000/mydatapod/profile/card#me ``` -This code does the setup for Bashlib, and installs the available modules. -Your `Bashlib` library is now setup and ready to use! - +which prompts to install bashlib, and on installation with show your WebID profile. -## Bashlib-css -To start with `Bashlib`, we first take a look at the `Bashlib-css` module. -The `Bashlib-css` module gives a set of functions specifically designed for the Community Solid Server. -It handles functionality that is currently not included in the spec for Solid and may vary between implementations of the Solid specification. -The CLI interface for `Bashlib-css` can be accessed here: +Alternatively, a local setup can be cloned from github. ``` -node bashlib/css/bin/css.js -``` -**optional:** You can create an alias for this path so you do not have to write the full command every time. From here on, I will assume the alias `alias bashlib-css="node bashlib/css/bin/css.js"` to be set! -### Creating a new Solid account + data pod -*compatbility: CSSv2.0.0 - current* - -A first function of the `Bashlib-css` module is the creation of a new Solid-account and accompanying data pod on a CSS instance. -This serves as an to having to use the browser interface to register a new user, which can be found on [http://localhost:3000/idp/register/](http://localhost:3000/idp/register/). - -To create a new Solid account and pod, please execute the following code: -``` -bashlib-css create-pod -``` -An interactive prompt will be shown, requiring you to enter the information of your to-be-created Solid account. - -e.g. -``` -? CSS instance base url http://localhost:3000/ -? Pod and user name Bob -? User email bob@test.edu -? User password bobIsTheBest123 -``` -This will result in the message that a pod for bob has been created succesfully on [http://localhost:3000/bob/profile/card#me](http://localhost:3000/bob/profile/card#me). If you navigate to this URL, you can now see the profile document of the newly created Solid account on the newly created Solid pod. +git clone https://github.com/SolidLabResearch/Bashlib.git +cd Bashlib +npm install +npm run build; -If you do not want an interactive prompt, you can use the command with all options enabled -``` -bashlib-css create-pod -b "http://localhost:3000/" -n Carol -e carol@test.edu -p carolIsTheBest123 +node bin/solid.js curl http://localhost:3000/mydatapod/profile/card#me ``` -to automatically create a new pod without requiring manual interaction. +**For the remainder of this tutorial, we will use `sld` as the alias for `npx solid-bashlib`.** -### Creating a Client Credentials token -*compatbility: CSSv4.0.0 - current* +## Managing Authentication +As Solid aims to provide secure online data management, +working with secured resources requires users to be +authenticated for the system to evaluate their access. -A second function of the `Bashlib-css` module is the creation of a [Client Credentials token](https://github.com/CommunitySolidServer/CommunitySolidServer/blob/main/documentation/client-credentials.md). -These tokens allow the user to authenticate without requiring user interaction by having them authenticate using a browser window. +The full documentation on the authentication options +for bashlib can be found in the authentication management section. -To create such a token, please execute the following code: -``` -bashlib-css create-token -``` +### Executing commands without authentication -This will again open an interactive prompt, requiring you to enter the information of the user registered on this Solid server for which you want to create the token: +To run commands over public data without any authentication, +we can start bashlib with the `--auth` flag set to none to +prevent it from automatically trying to authenticate requests. +We can for example make an unauthenticated request to our +created WebID as follows (WebID resources are always public): ``` -? Token name bobs-auth-token -? Pod baseuri http://localhost:3000/ -? User email bob@test.edu -? User password bobIsTheBest123 -? Token location .tokens/.bobs-auth-token +sld --auth none curl --header "Accept: application/n-triples" http://localhost:3000/mydatapod/profile/card#me ``` +This creates unauthenticated fetch request to the WebID resource +and outputs the result on the command line. As we passed a `--header` +option that requests the result in an n-triples format, the returned +data is formatted in an n-triples format. -You just succesfully created a Client Credentials token for Bob! -You can inspect the newly created token using `cat .tokens/.bobs-auth-token` to verify this. +### Setting a WebId and interactive authentication -This command can again be executed without an interactive prompt by providing values for all options: +However, for most personal use resource operations will require +the user to be authenticated. To start, we pass our created WebID +to Bashlib. This can either be done using the interactive interface +by running: ``` -bashlib-css create-token -v -b "http://localhost:3000/" -n carols-auth-token -e carol@test.edu -p carolIsTheBest123 -o .tokens/.carols-auth-token +sld auth set ``` - -### Authentication options -The `Bashlib-css` module exposes a set of authentication options. -These are however not exposed over the CLI interface, but are available in the Node.JS interface to use in your own Node.JS projects. -The `Bashlib-solid` module makes use of these options to authenticate the user on the CLI. - - -## Bashlib-solid -The `Bashlib-solid` module provides a set of functions to facilitate usage of and development for Solid from Node.JS and the CLI. -The CLI interface for `Bashlib-solid` can be accessed here: +and selecting the option: `Authenticate using new WebID` and providing +your WebID here. Alternatively, the WebID option can be provided +directly in the arguments as follows: ``` -node bashlib/solid/bin/solid.js +sld auth set http://localhost:3000/mydatapod/profile/card#me ``` -**optional**: You can create an alias for this path so you do not have to write the full command every time. From here on, I will assume the alias `alias bashlib-solid="node bashlib/solid/bin/solid.js"` to be set! - -### Authentication -Authentication in the `Bashlib-solid` module is done using the authentication options exposed by the `Bashlib-css` module. -We will quickly go over the available authentication options: - - -#### Authenticate using Client Credentials token -*compatbility: CSSv4 - current* -We can now use the client credentials token we made in [the previous step](#creating-a-client-credentials-token) to authenticate our user from the CLI. We can do this using the following authentication options: +To see the WebID used by Bashlib to authenticate requests, we can run ``` - bashlib-solid --auth token [options] +sld auth show --pretty ``` -Your identity provider is stored together with the token on your local filesystem, and does not have to be provided explicitly anymore. +which shows us that our WebID is now used by bashlib to authenticate requests. -We can now use the authenticated fetch command on private resources: -``` - bashlib-solid --auth token -t .tokens/.bobs-auth-token fetch http://localhost:3000/bob/profile/ -``` +However, now we've only told Bashlib our WebID, we have not yet given it the +means to authenticate a request using this WebID. There are two options for +authenticating with Bashlib to be able to make authenticated requests. +We can use an interactive authentication flow that uses our browser to authenticate, +or we can create a credentials token that we can store which will allow us to create +authenticated requests directly without needing an interactive browser session. -**note: This method of authentication is restricted to pods hosted on a Community Solid Server instance of v4.0.0 and later. If you have another provider, please use the interactive login option described below.** +Per default, Bashlib will use a dynamic authentication approach, where it will first look +if there is an active authenticated session it can reuse. If not, it will try to create a +new session using any stored credentials token. If none can be found, it will open a browser +window and have the user authenticate themselves interactively using the browser. - - -#### Interactive authentication -*compatbility: all* - -An alternative authentication method is the interactive login. -This option provides the default [Inrupt Node.JS authentication flow](https://docs.inrupt.com/developer-tools/javascript/client-libraries/tutorial/authenticate-nodejs/), and is compatible with all pods. -The interactive authentication requires the user to manually authenticate using their browser. +To create a listing of the profile directory of our Solid pod, run the following command: ``` - bashlib-solid --auth interactive --idp http://localhost:3000 [options] +npx solid-bashlib ls base:/profile/ ``` -We can now use the authenticated fetch command on private resources: -``` - bashlib-solid --auth interactive --idp http://localhost:3000 fetch http://localhost:3000/bob/profile/ -``` - -#### No authentication -*compatbility: all* +This `base:` is an alias for our pod root (`http://localhost:3000/mydatapod/`), +if it can be discovered from the user WebID. +Upon running the command, a browser window will pop-up asking the user to authenticate themselves. +Once logged in, looking back at the command line we see that a listing is displayed of the profile +container, which is only visible to the user WebID, so the authentication was successful. -Finally, you can just make use of the library without authenticating yourself. -This is the default option when no auth option is specified. +Additionally, running the listing command again, we see that no authentication is required, +as Bashlib stored the previous session, and reuses this session to authenticate subsequent +requests made for the same WebID. ``` - bashlib-solid --auth none [options] +npx solid-bashlib ls base:/profile --pretty ``` -We can now use fetch public resources as such: -``` - bashlib-solid --auth none fetch http://localhost:3000/bob/profile/card -``` - -### Commands -Now that we have created a Solid account and pod and learned how to authenticate, we will look at the available commands in `Bashlib-solid`. In this section, we will do a runthrough for all available commands, and how they can be used. -These commands will help you see solid not only as a Web technology, but as something you can easily include in existing workflows, while enabling ease of access and sharing of resources in between systems and users. -**We use the alias `alias bashlib-auth = "node bashlib/solid/bin/solid.js --auth token -t .tokens/.bobs-auth-token"` as a shortcut to make authenticated requests from here. In case you use another authentication method feel free to choose your own alias!** -#### URL Prefixes -All commands support URL prefixes for all URL parameters. -**Prefixes only work when the user is authenticated!** -Accepted prefixes are: - - `webid:` - The user WebID - - `inbox:` - The user inbox (if available) - - `root:` - The user storage root (only found if the WebID is inside te data pod) - - `base:` - Identical to `root:` - -For our user bob, we can now write the following url -``` - base:/public/resource1.ttl -``` -to define the resource located at +Looking at the current authentication status ``` - http://localhost:3000/bob/public/resource1.ttl +sldv auth show --pretty ``` -From here on out, we will make use of the prefixes, so feel free to authenticate with your own data pod, and follow the steps on your own pod environment. +we see that an active session is available now. -#### fetch / cat -The first command is the `fetch` command, with its twin the `cat` command. -Both commands have an identical result, of fetching and displaying the remote resource to `stdout`, -but the `fetch` command can take additional flags to pass custom headers and more. -To fetch the user webId, we can now call the following function: -``` - bashlib-auth fetch webid: -``` -As the authenticated user is Bob (see the alias we created), we just fetched bob's WebID. -Additional options can be found by calling the help function. -``` - bashlib-auth fetch --help -``` -If we want to fetch the file in an other RDF format, we can add custom headers: -``` - bashlib-auth fetch -h "Accept: application/ld+json" webid: -``` +### Creating a credentials token to automate authentication +However, having to authenticate interactions can be an overhead, +especially if commands are to be executed automatically from a script. +To automate the authentication flow, we need to make a token that will +allow us to do an authentication flow that does not require a browser window. -#### list / ls -The `list` or `ls` command displays a listing of a container on a Solid pod. -The url argument should end in a `/` as it must be a container. -Options can be discovered using the help command. +**Currently the generation of credential tokens that can directly authenticate a user session is only provided by the Community Solid Server and the Enterprise Solid Server.** +Both implementations differ however. In this section we only address the creation +of a token for the Community Solid Server. If you have a pod on an Enterprise Solid Server, +you can follow the documentation for +ESS token creation in the authentication section. -To list the resources in our profile folder, we use the following command: +To create the credentials token for our current WebID in Bashlib, we execute the following command: ``` - bashlib-auth ls base:/profile/ +sld auth create-token-css ``` +This will prompt us on if the token we want to create is for our currently logged in user. +Press `y` to continue. Now we are prompted for our email (bob@test.com) and password (bob). -By looking at the help function, we now will add the `--all` flag to also include any .acl files in the directory, and the `--long` flag to show a table overview of the result - +To confirm the generation of our token, we run the show command again, which now indicates we have an auth token present. ``` - bashlib-auth ls --all --long base:/profile/ +npx solid-bashlib auth show --pretty ``` +From now on, after session expiration, new sessions will be automatically generated through +this token without going through an interactive browser session. +**All authentication information is stored per default at ~/.solid/** -#### copy / cp -The `copy` or `cp` command copies resources form and to both the local filesystem and a data pod. -**Make sure you have read permissisons for the source location and write permissions for the destination location when they are on a pod.** - -We will demonstrate the copy command by uploading a profile image form our local disk. -If you have chosen a local image file, we can now upload this to our pod as follows: -``` - bashlib-auth cp contacts.ttl base:/profile/ -``` -This copies the `contacts.ttl` file to the container at the url `http://localhost:3000/bob/profile/`, and creates the contacts.ttl resource in this container. -We can now request the copied file as follows: -``` - bashlib-auth cat base:/profile/contacts.ttl -``` -We can also copy resources from one location on our pod to another location as follows: -``` - bashlib-auth cp base:/profile/contacts.ttl base:/test/ -``` -and can now fetch the resource at the target location -``` - bashlib-auth fetch base:/test/contacts.ttl -``` -We see that the missing containers were automatically created. -Notes: -- Directories are always copied recursively as a default. -- Copying files without an extension from the data pod will result in $., with the extension value based on the file contenttype. -- Copying a file `card$.ttl` to your data pod will result in a file `card` with a content type of `text/turtle`. -- Copying a file to a directory will place that file with the given filename in the destination directory. -- When directly copying an .acl file, the `--all` flag must not be set. -- Missing containers are automatically created. +## Managing authorization +Now that we have an authorized user, we can manage the authorization rules for the resources +on our Solid pod. Note that Solid has two competing authorization systems. The Web Access Controls +specification that uses `.acl` resources to manage resource access, and the Access Control Protocol +that uses `.acp` resources to manage resource access. -#### move / mv -The `move` or `mv` command moves resources between different locations on a data pod or between data pods. It is equal to a `cp` operation followed by a `rm` operation on the source. -**Make sure that the correct permissions are set to read and remove the source resources, and write to the destination resources.** +Bashlib implements two different access management regimes: It fully implements the WAC suite for +listing and editing permissions and removing permission resources, and it implements the universal +access suite that can work with both WAC and ACP access management systems. However this universal +system is less expressive in its functionality. +Bashlib will automatically detect the used access control mechanism, but enables additional functionality +when working with pods hosted on a WAC-based Solid Server such as access propagation and identity groups. -In the last section, we made a `contacts.ttl` resource in our `base:/test/` container. -We can now move the test resource we just made as a demonstration: +### Listing authorization +To list the permissions set on the root of our pod, run: ``` -bashlib-auth mv base:/test/contacts.ttl base:/test/demo_contacts.ttl +sld access list --pretty base:/ ``` +We see that our WebID has full permissions to read, write, append and control resources on our pod +(deleting a resource requires write permissions). +We also notice public read permissions on our root container, which we will change in the next section. +If our pod is hosted on a WAC-based Solid Server (such as the Community Solid Server we setup above), +we see the WebID permissions on our root are set as `default`, +meaning they are enforced on all sub-containers and resources of this root container +unless otherwise specified by these sub-containers or resources. +Additionally, the `inherited` field shows if this authorization state is +defined by an `.acl` file tied directly to the resource itself (in that case the value is no), +or if it was derived of a default permissions set by one of the resource parents (in that case the value is yes). -#### remove / rm -The `remove` or `rm` command removes resources from a data pod. +### Editing authorization -With this command, we can now remove the `demo_contacts.ttl` file in the `/test` folder: -``` -bashlib-auth rm base:/test/demo_contacts.ttl -``` -If we now look at the container listing: -``` -bashlib-auth ls base:/test/ +As shown above, currently our pod root container is set to be +publicly readable. To change these permissions, we set the public +access rights to our root container to be nothing. +When interacting pods hosted on a WAC-based Solid Server, we can use the `--default` flag to make +these access rules the default, however as the default access defined +by the system is no access, this makes no real difference in this case. +To do this, we run the following command: ``` -we see that the resource has been removed. -We can also remove the container now as follows: +sld access set base:/ p= ``` -bashlib-auth rm base:/test/ -``` -To remove a container together with the contained resources, the `-r, --recursive` flag has to be set. - - -#### mkdir -The `mkdir` command creates a target container. +The `base:/` value targets our pod root container. +The `p` value sets the access target as `public`, +and the empty space after the `=` symbol indicates +that the permissions given to the public are none. +We confirm this by listing the permissions again: ``` -bashlib-auth mkdir base:/Pictures/ +sld access list --pretty base:/ ``` -creates a new `Pictures/` container in the root of your pod. - -#### touch -The `touch` command creates a target resource in a container. - +showing public read permissions are not set anymore. +Additionally, we see that a resource request to the +full URI gives us a `401 Unauthenticated` response. ``` -bashlib-auth touch base:/test.txt +sld --auth none curl http://localhost:3000/mydatapod/ ``` -creates a new resource `test.txt` in the root of your pod. - -#### find -The `find` command enables you to find specific files in a given container based on a given filename regex. -If we want to find where our profile card is located on our data pod, we can use the following command: +If we now want to create an inbox container, to which +people can write resources but not read resources, +we first make a new directory ``` -bashlib find --full base: card +sld mkdir base:/inbox/ ``` -This command looks to match all found files in the `base:` container with the given filename match `card`. -We use the `--full` flag to match with and display the full url of the found resources. - -#### query -The `query` command is a convenience command that lets the user query one file or all files in a container based on a given SPARQL query. - -To return all triples from our WebID, we can use the following command: +that we can confirm in our listing to exist now: ``` -bashlib-auth query webid: "Select * WHERE { ?s ?p ?o . }" +sld ls base:/ ``` -This command also works on containers to recursively query all contained resources. -To test this, we first make a new file containing a SPARQL query: -``` -echo "Select * WHERE { ?s ?p ?o . }" > queryFile.txt +Listing permissions for this created container, we see +that no public permissions are set for this container. ``` -Now, we can use this query to get all triples of all files on our data pod. We use the `--pretty` flag to receive the results in a table format: +sld access list --pretty base:/inbox/ ``` -bashlib-auth query -q -p base: queryFile.txt -``` - - -#### perms -The `perms` command provides three operations to list, edit and delete permissions for a resource on a Solid pod. -**This command only works for pods implementing the WAC protocols. Pods implementing the ACP protocol (Inrupt) are currently not supported.** -***listing*** - -To list the permissions of your profile resource, we can use the following command: +Now, we set public read permissions for this resource: ``` -bashlib-auth perms list webid: +sld access set base:/inbox/ p=w ``` -Here, we see the permissions written out for all agents, groups and the public for the given resource. -This also works for containers. The following command prints the permissions of the pod root in a table format: +Listing permissions again shows that now only read permissions +are assigned to this container. ``` -bashlib-auth perms list --pretty base: +sld access list --pretty base:/inbox/ ``` -***editing*** -**note: The editing of permissions for containers and other resources is exactly the same.** - -To demonstrate the editing of permissions, we will first create a `Private` and `Public` folder on our pod. +Note that setting permissions for an identifier removes +any existing permissions. Setting read permissions as follows ``` -bashlib-auth mkdir base:/Private/ -bashlib-auth mkdir base:/Public/ +sld access set base:/inbox/ p=r ``` - -We start by setting the permissions for the `base:/Public/` container to be publicly readable, and make this the default for all contained resources (only an option for WAC). +will remove the existing write permission, as we did not renew it +in this operation. ``` -bashlib-auth perms edit base:/Public/ p=rd +sld access list --pretty base:/inbox/ ``` -When we now list the resource permissions, we see that public permissions are set to `read` and `default`. +To give access to our contact to also read our inbox, +we assign access rules for their WebID. ``` -bashlib-auth perms list --pretty base:/Public/ +sld access set base:/inbox/ https://poeple.org/alice/webid=r ``` +Listing the permissions now we see Alice has been given read access to our inbox container. -Now we want to make sure the public cannot read or interact in any way with out `Private` container. -For this we set public permissions to be nothing. -However, we want our currently authenticated user to have full permissions in this container and all contained resources as a default (append permissions are implicitly set by giving write permissions): -``` -bashlib-auth perms edit base:/Private/ p= u=rwcd -``` -When we now list the resource permissions, we see that no public permissions are set. We also see that the permissions are NOT inherited, meaning they are have been set for the resource successfully. -``` -bashlib-auth perms list --pretty base:/Private/ -``` +## Requesting and querying resources +In addition to authentication and authorization management, Bashlib provides a set of +commands aimed at the requesting and querying of resources that we will go over here. +The documentation for every command can be found here. -Finally, we want to give permission to our friend with the WebID `https://my.friends.pod/profile/card#me` to read and write in our `Private` container. -For this we use the following command: +The first command we have already touched upon is `curl`. It mimics the curl command provided by BASH +and provides options for choosing the HTTP method, the body and more. +Simply executing a curl on a URL performs a GET request. ``` -bashlib-auth perms edit base:/Private/ https://my.friends.pod/profile/card#me=rw +sld curl base:/ ``` -When we now list the resource permissions, we see that our friend `https://my.friends.pod/profile/card#me` had received read, write and append (implicitly given through write) permissions over our `Private` container. +The next command we have seen before is the `ls` command. +It outputs a listing of the targeted container, and can be +made to include access control and metadata resources present +in the container as well. ``` -bashlib-auth perms list --pretty base:/Private/ +sld ls -la base:/ ``` -***deleting*** -Finally, we can also delete resource permissions. -We can remove the permissions set for a given resource. - -To remove the permissions set for the public container, we can use the following command: +The `tree` command allows us to create a directory tree +starting from the targeted container. ``` -bashlib-auth perms delete base:/Public/ +sld tree base:/ ``` -If we now list the permissions for this container, we see that all current permissions are inherited from the parent container, as the permissions for the `Public` container have been deleted. +The `cp` command allows the copying of resources on the same pod, +between pods, or from and to the local file system. It per default +is fully recursive, and will copy the whole underlying resource +tree to the target destination. ``` -bashlib-auth perms list --pretty base:/Public/ +sld cp /path/to/img.png base:/images/img.png ``` - -#### edit -The edit command is a helper command to quickly allow you to edit resources on your pod. -The command takes the url of a resource (cannot be a container), copies the resource to your local filesystem and opens the resource with your given or your default editor. - -We will now edit the file `base:/Public/test.txt` with our local vim editor. -If you do not have vim installed, please select your prefered editor or do not use the flag to use the default system editor. -Using the `--touch` flag, we will create a new file if the resource does not exist yet. +The `mv` command is similar to the copy command, but it removes the +source resources after the move (except for when moving from the local +file system). ``` -bashlib-auth edit --editor vim --touch base:/Public/test.txt +sld mv base:/images/img.png base:/photos/. ``` -Now your editor will open with an empty file. -You can now edit the file to contain a string of text, and then save the file in your editor. -On exiting the editor, and returning to the terminal, you must press any button to continue. -Now, the edited resource will be copied from your local filesystem to its location on the data pod, and be removed from the local filesystem. - -If we now look at the created file +The `rm` command can be used to remove resources and containers from +a Solid pod. It requires an explicit flag to work recursive. ``` -bashlib-auth cat base:/Public/test.txt +sld rm -r base:/photos/ ``` -we see that the file has been created and contains the text that was written in the editor. - - - - - -## Examples -In this section, we will go over some quick examples of how the CLI interface of `Bashlib` can be used to do some common tasks. -For all examples, we will make use of the following aliases: - -- bashlib-css - `alias bashlib-css="node bashlib/css/bin/css.js"` -- bashlib-solid - `alias bashlib-auth="node bashlib/solid/bin/solid.js"` -- bashlib-auth - `alias bashlib-auth="node bashlib/solid/bin/solid.js" --auth ` - -### Creating a new pod and authentication token -*compatibility CSSv4 - current* - -First, we need to have a Community Solid Server instance running. More info on how to setup a Community Solid Server can be found [here](https://github.com/CommunitySolidServer/CommunitySolidServer). - -First, we create a new pod on our running CSS instance. -For this we run the `create-pod` command: -``` -bashlib-css create-pod +The `mkdir` command creates an empty container on a Solid pod. ``` -and we fill in the required information: -``` -? CSS instance base url your CSS server baseURL, e.g. http://localhost:3000/ -? Pod and user name the name for your pod -? User email the email address to login to the pod -? User password the password to login to the pod +sld mkdir base:/documents/ ``` -On completion, you will receive the following message +The `touch` command creates an empty resource ``` -Pod for created succesfully on //profile/card#me +sld touch base:/documents/work/file.txt ``` -This `//profile/card#me` is the WebID of your newly created Solid account. -Now that we have created a Solid account, we will create an authentication token we can use to authenticate to our pod from the CLI. For this, we use the `create-token` command. -``` -bashlib-css create-token -``` -and fill in the required information: +The `find` command searches all resources in the given container and its sub-containers for a name match. ``` -? Token name the name of the token e.g. my-cli-auth-token -? Pod baseuri your CSS server baseURL, e.g. http://localhost:3000/ -? User email the email address to login to the pod -? User password the password to login to the pod -? Token location you can choose a custom location or leave this blank to default to ~/.solid/.css-auth-token +sld find base:/ file.txt ``` -This creates a client-credentials-token you can use to authenticate at the `Token location` (default is `~/.solid/.css-auth-token`). With this token, we can now authenticate our commands, such as listing the permissions of our WebID profile resource. - -In case the default location was used to store the token, we use the following command -``` -bashlib-solid --auth "token" perms list --pretty webid: -``` -In case a custom token location was given, we pass the `-t` flag to indicate where the token can be found: +The `find` command evaluates a query over all resources in the given container and its sub-containers individually. +The `--federated` flag can be used to evaluate the query over the combined knowledge graph of all found resources. ``` -bashlib-solid --auth "token" -t perms list --pretty webid: +sld query --all base:/ "Select ?person where { ?person . }" ``` -You can alias this to have a quick and easy way to use `Bashlib` from the cli (-t option only required if the default storage location was not used): +The `edit` command opens a remote resource in a local editor. It copies the resource to a temporary file, +after which changes can be committed to this file. Upon pressing a button in the Bashlib program, this +temporary file is synced again with the remote resource. ``` -alias bashlib-auth=`bashlib-solid --auth "token" -t -``` -From here on, you can use this alias to make all your commands authenticated: -``` -bashlib-auth perms list --pretty webid: +sld edit base:/documents/work/file.txt ``` +## Setting up a profile image on your pod -### Setting up a profile image on your pod -Here we will discuss how we can quickly add a profile image to our profile, and store it on our pod. For this, we first need to choose a profile image. Say we have a nice image we want to use for this at `~/Pictures/my_nice_picture.png`. +Let's end with a concrete task, setting a profile picture. +We choose our profile picture located at `~/Pictures/my_nice_picture.png`. -First, we copy the image to our pod at the location `base:/profile/img.png`. +To start, we copy the image to our pod at the location `base:/profile/img.png` using the following command: ``` -bashlib-auth cp ~/Pictures/my_nice_picture.png base:/profile/img.png +sld cp ~/Pictures/my_nice_picture.png base:/profile/img.png ``` -Next, we will make this image publicly readable, so everyone can see your profile picture. If you do not like this, feel free to only add read permissions for specific WebIDs. +As profile pictures need to be publicly readable, so everyone can see your profile picture, +we set public read permissions for this resource. ``` -bashlib-auth perms edit base:/profile/img.png p=r +sld access set base:/profile/img.png p=r ``` -With our image uploaded to our pod and made public, we will now have to edit our profile document to link the new profile image to our WebID. +With our image uploaded to our pod and made public, +we will now have to edit our profile document to link the new profile image to our WebID +(use the `--editor` option to choose an alternative editor) ``` -bashlib-auth edit webId: +sld edit webId: ``` -This will open our profile document in our default editor. +This will open our profile document in our default editor (or our editor of choice). We now add the following line to the document (replace `imageurl` with the url of the newly uploaded image): ``` -<#me> . + . ``` Now save the document, and exit the editor. Press on any key to continue, and your profile document is now updated with a link to your newly added profile image -Congratulations, you just set your profile image. +Congratulations, you just set your profile image! + +If you were using a web-hosted Solid pod, you should be able to see your result when looking at your profile +here. For locally hosted pods however, +most likely your browser will stop you from looking at localhost links because of CORS errors. diff --git a/documentation/site/404.html b/documentation/site/404.html index 20f2e1a..2cc1b08 100644 --- a/documentation/site/404.html +++ b/documentation/site/404.html @@ -472,8 +472,6 @@ - - @@ -514,27 +512,6 @@ -
  • - - - - - Overview - - - - -
    • - - - - - - - - - -
  • @@ -578,11 +555,11 @@
  • - + - Manage Authentication + Manage Resource Access diff --git a/documentation/site/contributing/making-changes/index.html b/documentation/site/contributing/making-changes/index.html index e6a9b6d..8eaf720 100644 --- a/documentation/site/contributing/making-changes/index.html +++ b/documentation/site/contributing/making-changes/index.html @@ -479,8 +479,6 @@ - - @@ -521,27 +519,6 @@ -
  • - - - - - Overview - - - - -
    • - - - - - - - - - -
  • @@ -585,11 +562,11 @@
  • - + - Manage Authentication + Manage Resource Access diff --git a/documentation/site/documentation/cli/access/index.html b/documentation/site/documentation/cli/access/index.html index b8b9414..8a9bf45 100644 --- a/documentation/site/documentation/cli/access/index.html +++ b/documentation/site/documentation/cli/access/index.html @@ -11,6 +11,10 @@ + + + + @@ -18,7 +22,7 @@ - Access Management - Bashlib + Manage Resource Access - Bashlib @@ -120,7 +124,7 @@
    - Access Management + Manage Resource Access
    @@ -262,10 +266,12 @@ + + -
  • +
  • @@ -403,6 +409,8 @@ + + @@ -415,18 +423,21 @@ + + + -
  • +
  • - + -
    • @@ -598,26 +858,18 @@ - - -
  • - - - - - - +
  • + - Manage Authentication + Manage Resource Access -
    • @@ -676,6 +928,262 @@ + + + + + @@ -690,9 +1198,148 @@ -

    Manage Authentication

    - - +

    Authentication Management

    +

    The Bashlib CLI interface provides multiple options for authentication management. +It enables interactive login flows using the browser, that work with any Solid pod server. +Additionally, it includes the client credentials flow to generate authentication tokens without needing a browser login +both for the Community Solid Server v7 and the Enterprise Solid Server from Inrupt.

    +


    +All examples make use of the abstraction sld as an alias for node bin/solid.js,

    +

    Enforcing specific authorization flows

    +

    When setting up test flows on Solid, it might be interesting to force a specific authentication flows to be used. +For this, the --auth option can be set on the bashlib program as such:] +

    sld --auth interactive
+
    +This examples forces authentication via an interactive browser session. Other options are token for only token based authentication, +none for no authentication and request to dynamically choose an authentication option during use, which is the default. +The --port option can be changed to change the port of the local service that is setup to manage interactive authentication flows with the browser.

    +

    Auth command

    +

    The auth command contains all functionality to manage authentication options and create client credentials tokens.

    +

    Set

    +

    The set subcommand is used to manage the authentication session for Bashlib. +It provides the ability to set a specific WebID as an argument, or if no argument is given starts an interactive selection dialog to change the active WebID.

    +

    arguments

    +

    Arguments:
+  webid       Set active WebID directly, without requiring manual selection.
+
    +The webid argument directly sets the session to the provided WebID value.

    +

    examples

    +

    Interactive session management +

    sld auth set
+

    +

    Setting a specific active WebID +

    sld auth set https://people.org/alice/webid
+

    +

    Show

    +

    The show subcommand shows the current authentication session. It shows the WebId, if there is an active authentication session and if a client credential token is available.

    +

    options

    +

    Options:
+  -p, --pretty  Show listing in table format.
+
    +The --pretty option displays the result in a table formate.

    +

    examples

    +
    sld auth show
+
    +

    Clear

    +

    The clear subcommand clears the current authentication session and active WebID. It does not remove any stored authentication information.

    +

    examples

    +
    sld auth clear
+
    +

    List

    +

    The list subcommand lists the stored authentication information. It shows the WebIds, if there is an active authentication session and if a client credential token is available.

    +

    options

    +

    Options:
+  -p, --pretty  Show listing in table format.
+
    +The --pretty option displays the result in a table formate.

    +

    examples

    +
    sld auth list
+
    +

    Remove

    +

    The remove subcommand provides the ability to remove authentication information from Bashlib. +It provides an interactive menu if no argument is given, or can remove information for specific WebIDs or all information directly via the CLI arguments.

    +

    arguments

    +

    Arguments:
+  string      webid | all
+
    +The command has an optional parameter. +When passing the argument string all, all authentication information is removed. +Passing a specific WebID removes all authentication information tied to that WebID. +If no argument is passed, an interactive CLI menu is provided.

    +

    examples

    +

    Opening the interactive menu +

    sld auth remove
+

    +

    Removing all authentication information +

    sld auth remove all
+

    +

    Removing a specific WebID +

    sld auth remove https://people.org/alice/webid
+

    +

    Create Token (CSS)

    +

    The token creation is divided in two subcommands, +one for the Community Solid Server and one for the Inrupt Enterprise Solid Server, +as both have a different approach to token generation for client applications.

    +

    The create-token-css command creates a client credentials token for pods hosted on +a Community Solid Server version 7. The authentication options can be passed both +as command line arguments, or in an interactive dialog if they are not provided through +the CLI options. +The interactive creation menu will ask to use the WebID of the current session to create +a token when available.

    +

    options

    +

    Options:
+  -w, --webid <string>     User WebID
+  -n, --name <string>      Token name
+  -e, --email <string>     User email
+  -p, --password <string>  User password
+  -v, --verbose            Log actions
+  -h, --help               display help for command
+
    +The --webid option is the WebID for which the token is created. +
    +The --name option is the name of the token (only important for token management). +
    +The --email option is the email that was used to create the account tied to the WebID. +
    +The --password option is the password tied to the account. +
    +the --verbose option outputs operation logs.

    +

    examples

    +

    Open interactive dialog to create token +

    sld auth create-token-css
+

    +

    Create Token (ESS)

    +

    The create-token-ess command creates a client credentials token for pods hosted on +an Inrupt Enterprise Solid Server. The authentication options can be passed both +as command line arguments, or in an interactive dialog if they are not provided through +the CLI options. +The interactive creation menu will ask to use the WebID of the current session to create +a token when available. +
    +The Inrupt token generation relies on the registration of applications via their +application registration service. +After registering Bashlib, an id and secret value will be shown. These values need +to be provided to this command to be able to automatically create authenticated sessions +without needing interactive login.

    +

    options

    +

    Options:
+  -w, --webid <string>     User WebID
+  -i, --id <string>        application registration id
+  -s, --secret <string>    application registration secret
+  -v, --verbose            Log actions
+  -h, --help               display help for command
+
    +The --webid option is the WebID for which the token is created. +
    +The --id option is the id value retrieved from the registration flow described above. +
    +The --secret option is the secret value retrieved from the registration flow described above. +
    +the --verbose option outputs operation logs.

    +

    examples

    +

    Open interactive dialog to create token +

    sld auth create-token-ess
+

    diff --git a/documentation/site/documentation/cli/commands/index.html b/documentation/site/documentation/cli/commands/index.html index 46724b8..7f937a7 100644 --- a/documentation/site/documentation/cli/commands/index.html +++ b/documentation/site/documentation/cli/commands/index.html @@ -14,7 +14,7 @@ - + @@ -492,8 +492,6 @@ - - @@ -534,27 +532,6 @@ -
  • - - - - - Overview - - - - -
    • - - - - - - - - - -
  • @@ -1118,11 +1095,11 @@
  • - + - Manage Authentication + Manage Resource Access @@ -1761,27 +1738,28 @@

    Copy&par If the source location is a container or directory, it will recursively copy the container and all sub-containers recursively copying the whole underlying resource tree, including empty containers.

    The default copying behavior ignores .meta, .acl and .acp resources, which can be changed using the --all flag. -The default behavior is to overwrite files, the --interactive-override and --no-override options provide alternative behaviors.

    +The copy command automatically copies the full recursive resource tree. At the moment this behavior cannot be altered. +In terms of overriding resources, the default setting is that every time a resource is found to already exist, an interactive prompt is shown. +This behavior can be altered either by the --never-override or the --override options.

    arguments

    Arguments:
-  src                         file or directory to be copied
-  dst                         destination to copy file or directory to
+  src                   resource or container to be copied
+  dst                   destination to copy file or directory to
    The src argument is the location of the resource or container to be moved. If the URL starts with http(s)://, the resource is assumed to be a remote resource, if not the resource is assumed to be local and matched with the local file system. The dst argument is the destination to which the source resource is to be copied. Similarly it uses the http(s):// prefix to decide if the location is local or remote. -The default behavior ignores context resources such as .meta, .acl and .acp present in the directories. The --all flag ignores this behavior, though note that for authorization resources, as the target URIs are not edited, copying resources with these authorization resources does not imply they will result in the same access controls as the location they were copied from! -The default behavior always automatically works recursively. At the moment this behavior cannot be altered.

    +The default behavior ignores context resources such as .meta, .acl and .acp present in the directories. The --all flag ignores this behavior, though note that for authorization resources, as the target URIs are not edited, copying resources with these authorization resources does not imply they will result in the same access controls as the location they were copied from!

    options

    Options:
-  -a, --all                   Copy .acl files in recursive directory copies
-  -i, --interactive-override  Interactive confirmation prompt when overriding existing resource
-  -n, --no-override           Do not override existing files
-  -v, --verbose               Log all read and write operations
+  -a, --all             Copy .acl files in recursive directory copies
+  -o, --override        Automatically override existing files
+  -n, --never-override  Automatically override existing files
+  -v, --verbose         Log all read and write operations
    The --all option includes .meta, .acl and .acp files in the listing.
    -The --interactive-override option provides an interactive prompt when a copy will override an existing resource. +The --override option automatically overrides existing resources.
    -The --no-override option ignores existing resources. +The --never-override option automatically mitigates resource overrides.
    The --verbose option shows warnings.

    examples

    @@ -1806,27 +1784,28 @@

    Move&par When moving from the local file system, files will not be deleted!

    The default copying behavior ignores .meta, .acl and .acp resources, which can be changed using the --all flag. -The default behavior is to overwrite files, the --interactive-override and --no-override options provide alternative behaviors. -The default behavior always automatically works recursively. At the moment this behavior cannot be altered.

    +The move command automatically moves the full recursive resource tree. At the moment this behavior cannot be altered. +In terms of overriding resources, the default setting is that every time a resource is found to already exist, an interactive prompt is shown. +This behavior can be altered either by the --never-override or the --override options.

    arguments

    Arguments:
-  src                         file or directory to be moved
-  dst                         destination of the move
+  src                   resource or container to be moved
+  dst                   destination of the move
    The src argument is the location of the resource or container to be moved. If the URL starts with http(s)://, the resource is assumed to be a remote resource, if not the resource is assumed to be local and matched with the local file system. The dst argument is the destination to which the source resource is to be copied. Similarly it uses the http(s):// prefix to decide if the location is local or remote. The default behavior ignores context resources such as .meta, .acl and .acp present in the directories. The --all flag ignores this behavior, though note that for authorization resources, as the target URIs are not edited, copying resources with these authorization resources does not imply they will result in the same access controls as the location they were copied from!

    options

    Options:
-  -a, --all                   Move .acl files when moving directories recursively
-  -i, --interactive-override  Interactive confirmation prompt when overriding existing files
-  -n, --no-override           Do not override existing files
-  -v, --verbose               Log all operations
+  -a, --all             Copy .acl files in recursive directory copies
+  -o, --override        Automatically override existing files
+  -n, --never-override  Automatically override existing files
+  -v, --verbose         Log all read and write operations
    The --all option includes .meta, .acl and .acp files in the listing.
    -The --interactive-override option provides an interactive prompt when a copy will override an existing resource. +The --override option automatically overrides existing resources.
    -The --no-override option ignores existing resources. +The --never-override option automatically mitigates resource overrides.
    The --verbose option shows warnings.

    examples

    diff --git a/documentation/site/documentation/cli/overview/index.html b/documentation/site/documentation/cli/overview/index.html deleted file mode 100644 index f7e8ffd..0000000 --- a/documentation/site/documentation/cli/overview/index.html +++ /dev/null @@ -1,785 +0,0 @@ - - - - - - - - - - - - - - - - - - - - - - - - - Overview - Bashlib - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    - -
    - - - - - - -
    - - -
    - -
    - - - - - - - - - -
    -
    - - - -
    -
    -
    - - - - - - - -
    -
    -
    - - - -
    -
    -
    - - - -
    -
    -
    - - - -
    -
    - - - - -

    Overview Usage for CLI

    -

    The command line interface provides a set of basic interactions -to work with the resources on a Solid pod.

    -

    Introduce Authentication

    -

    Introduce Commands

    -

    Introduce Shortcuts

    - - - - - - - - - - - - - -
    -
    - - - -
    - - - -
    - - - -
    -
    -
    -
    - - - - - - - - - - \ No newline at end of file diff --git a/documentation/site/documentation/overview/index.html b/documentation/site/documentation/overview/index.html index e8ac76e..151f21b 100644 --- a/documentation/site/documentation/overview/index.html +++ b/documentation/site/documentation/overview/index.html @@ -14,7 +14,7 @@ - + @@ -74,7 +74,7 @@
    - + Skip to content @@ -500,8 +500,6 @@ - - @@ -542,27 +540,6 @@ -
  • - - - - - Overview - - - - -
    • - - - - - - - - - -
  • @@ -606,11 +583,11 @@
  • - + - Manage Authentication + Manage Resource Access @@ -689,7 +666,21 @@ -

    Overview Usage

    +

    Documentation Overview

    +

    The Bashlib command line interface provides straightforward commands to interact with your Solid pod. +It can be useful both for personal use, setting up small workflows or quick demonstrations of proof of concepts. +The authentication options enable quick switching between WebIDs and Solid Pods. +
    +As not everything is optimized for performance, operations that target many resources or few but large resources +may not be performant enough for some use-cases, as the internal resource management does not make use of streaming.

    +


    +To login and manage authentication info for Bashlib, navigate to the authentication management section. +
    +For an overview of the available commands, their options and code example, navigate to the available commands section. +
    +To view and manage access to resources, navigate to the access management section. +
    +To see how to use aliases to speed up your flow, navigate to the using aliases section.

    diff --git a/documentation/site/documentation/typescript/authentication/index.html b/documentation/site/documentation/typescript/authentication/index.html index 8ee7758..bf105da 100644 --- a/documentation/site/documentation/typescript/authentication/index.html +++ b/documentation/site/documentation/typescript/authentication/index.html @@ -474,8 +474,6 @@ - - @@ -516,27 +514,6 @@ -
  • - - - - - Overview - - - - -
    • - - - - - - - - - -
  • @@ -580,11 +557,11 @@
  • - + - Manage Authentication + Manage Resource Access diff --git a/documentation/site/documentation/typescript/css-specific/index.html b/documentation/site/documentation/typescript/css-specific/index.html index 92acac7..101a655 100644 --- a/documentation/site/documentation/typescript/css-specific/index.html +++ b/documentation/site/documentation/typescript/css-specific/index.html @@ -479,8 +479,6 @@ - - @@ -521,27 +519,6 @@ -
  • - - - - - Overview - - - - -
    • - - - - - - - - - -
  • @@ -585,11 +562,11 @@
  • - + - Manage Authentication + Manage Resource Access diff --git a/documentation/site/documentation/typescript/example-requests/index.html b/documentation/site/documentation/typescript/example-requests/index.html index 0321bca..4ac79aa 100644 --- a/documentation/site/documentation/typescript/example-requests/index.html +++ b/documentation/site/documentation/typescript/example-requests/index.html @@ -479,8 +479,6 @@ - - @@ -521,27 +519,6 @@ -
  • - - - - - Overview - - - - -
    • - - - - - - - - - -
  • @@ -585,11 +562,11 @@
  • - + - Manage Authentication + Manage Resource Access diff --git a/documentation/site/documentation/typescript/metadata/index.html b/documentation/site/documentation/typescript/metadata/index.html index 039d222..cfcc17d 100644 --- a/documentation/site/documentation/typescript/metadata/index.html +++ b/documentation/site/documentation/typescript/metadata/index.html @@ -479,8 +479,6 @@ - - @@ -521,27 +519,6 @@ -
  • - - - - - Overview - - - - -
    • - - - - - - - - - -
  • @@ -585,11 +562,11 @@
  • - + - Manage Authentication + Manage Resource Access diff --git a/documentation/site/documentation/typescript/overview/index.html b/documentation/site/documentation/typescript/overview/index.html index 6b4de14..266cf2a 100644 --- a/documentation/site/documentation/typescript/overview/index.html +++ b/documentation/site/documentation/typescript/overview/index.html @@ -479,8 +479,6 @@ - - @@ -521,27 +519,6 @@ -
  • - - - - - Overview - - - - -
    • - - - - - - - - - -
  • @@ -585,11 +562,11 @@
  • - + - Manage Authentication + Manage Resource Access diff --git a/documentation/site/index.html b/documentation/site/index.html index f92bbd9..0742668 100644 --- a/documentation/site/index.html +++ b/documentation/site/index.html @@ -490,8 +490,6 @@ - - @@ -532,27 +530,6 @@ -
  • - - - - - Overview - - - - -
    • - - - - - - - - - -
  • @@ -596,11 +573,11 @@
  • - + - Manage Authentication + Manage Resource Access @@ -683,14 +660,16 @@

    Welcome

    Welcome to the Bashlib Homepage.

    -

    The documentation here is still incomplete both in content and structure, so feel free to open -a discussion about things you want to see added. -While we try to update this documentation together with updates in the code, -it is always possible we miss something, -so please report it if you find incorrect information or links that no longer work.

    -

    An introductory tutorial can be found -here. -This is a good way to get started with the server and its setup.

    +

    Bashlib is a Command Line Interface for working with Solid Pods, made by +Ruben Dedecker at the +KNoWS team at Ghent University.

    +

    An introduction to quickly setting up a Community Solid Server instance and +interfacing with it using Bashlib is found in the tutorial section.

    +

    Documentation on the tool and the available commands is found in +the documentation section.

    +

    Documentation may be incomplete in content and structure. +Feel free to open a discussion +and report incorrect information.

    diff --git a/documentation/site/search/search_index.json b/documentation/site/search/search_index.json index a5334c9..be5ab2a 100644 --- a/documentation/site/search/search_index.json +++ b/documentation/site/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Welcome","text":"

    Welcome to the Bashlib Homepage.

    The documentation here is still incomplete both in content and structure, so feel free to open a discussion about things you want to see added. While we try to update this documentation together with updates in the code, it is always possible we miss something, so please report it if you find incorrect information or links that no longer work.

    An introductory tutorial can be found here. This is a good way to get started with the server and its setup.

    "},{"location":"tutorial/","title":"Bashlib Tutorial - CLI edition","text":"

    This tutorial aims to teach the basics of the Solid Bashlib library. This tutorial only regards the CLI interface of the Bashlib library. For the Node.JS interface, please look at the Bashlib tutorial - Node.JS edition!

    Used aliases in this document: All aliases are calculated from the root of the cloned bashlib repo. - bashlib-css - alias bashlib-css=\"node bashlib/css/bin/css.js\" - bashlib-solid - alias bashlib-solid=\"node bashlib/solid/bin/solid.js\" - bashlib-auth - alias bashlib-auth=\"node bashlib/solid/bin/solid.js --auth token -t .tokens/.bobs-auth-token\" Feel free to use a different authentication scheme for the bashlib-auth alias.

    "},{"location":"tutorial/#index","title":"Index","text":"
    • Bashlib Tutorial - CLI edition
    • Index
    • Setting up a Solid Server
    • Setting up Bashlib
    • Bashlib-css
      • Creating a new Solid account + data pod
      • Creating a Client Credentials token
      • Authentication options
    • Bashlib-solid
      • Authentication
      • Authenticate using Client Credentials token
      • Interactive authentication
      • No authentication
      • Commands
      • URL Prefixes
      • fetch / cat
      • list / ls
      • copy / cp
      • move / mv
      • remove / rm
      • mkdir
      • touch
      • find
      • query
      • perms
      • edit
    • Examples
      • Creating a new pod and authentication token
      • Setting up a profile image on your pod
    "},{"location":"tutorial/#setting-up-a-solid-server","title":"Setting up a Solid Server","text":"

    Before we use the Bashlib library, we need a Solid account and accompanying data pod to use the library. In case you already own a Solid pod, you may still want to follow the setup process, as some of the functionality will only be available for pods created on a Community Solid Server instance.

    To setup a Solid Server where we can register an account and get an accompanying data pod, we will make use in this tutorial of the Community Solid Server.

    To setup a local Community Solid Server instance, please execute the code below. More information on the setup process can be found here. When you are done with the tutorial, you can remove the current folder to delete all created files.

    git clone https://github.com/CommunitySolidServer/CommunitySolidServer.git\ncd CommunitySolidServer/\nnpm install\nnpm start\n

    Congratulations! Your own CSS instance is now running on localhost on port 2323. You can confirm this by browsing to http://localhost:3000 in the browser, and you will be greeted with a setup screen. You do not have to do anything on this screen for now!

    "},{"location":"tutorial/#setting-up-bashlib","title":"Setting up Bashlib","text":"

    To setup the Bashlib library, we execute the following code: 

    git clone https://github.com/SolidLabResearch/Bashlib.git\ncd Bashlib\nbash setup.sh\n
    This code does the setup for Bashlib, and installs the available modules. Your Bashlib library is now setup and ready to use!

    "},{"location":"tutorial/#bashlib-css","title":"Bashlib-css","text":"

    To start with Bashlib, we first take a look at the Bashlib-css module. The Bashlib-css module gives a set of functions specifically designed for the Community Solid Server. It handles functionality that is currently not included in the spec for Solid and may vary between implementations of the Solid specification. The CLI interface for Bashlib-css can be accessed here: 

    node bashlib/css/bin/css.js\n
    optional: You can create an alias for this path so you do not have to write the full command every time. From here on, I will assume the alias alias bashlib-css=\"node bashlib/css/bin/css.js\" to be set!

    "},{"location":"tutorial/#creating-a-new-solid-account-data-pod","title":"Creating a new Solid account + data pod","text":"

    compatbility: CSSv2.0.0 - current

    A first function of the Bashlib-css module is the creation of a new Solid-account and accompanying data pod on a CSS instance. This serves as an to having to use the browser interface to register a new user, which can be found on http://localhost:3000/idp/register/.

    To create a new Solid account and pod, please execute the following code: 

    bashlib-css create-pod \n
    An interactive prompt will be shown, requiring you to enter the information of your to-be-created Solid account.

    e.g. 

    ? CSS instance base url   http://localhost:3000/\n? Pod and user name       Bob\n? User email              bob@test.edu\n? User password           bobIsTheBest123 \n
    This will result in the message that a pod for bob has been created succesfully on http://localhost:3000/bob/profile/card#me. If you navigate to this URL, you can now see the profile document of the newly created Solid account on the newly created Solid pod.

    If you do not want an interactive prompt, you can use the command with all options enabled 

    bashlib-css create-pod -b \"http://localhost:3000/\" -n Carol -e carol@test.edu -p carolIsTheBest123\n
    to automatically create a new pod without requiring manual interaction.

    "},{"location":"tutorial/#creating-a-client-credentials-token","title":"Creating a Client Credentials token","text":"

    compatbility: CSSv4.0.0 - current

    A second function of the Bashlib-css module is the creation of a Client Credentials token. These tokens allow the user to authenticate without requiring user interaction by having them authenticate using a browser window.

    To create such a token, please execute the following code: 

    bashlib-css create-token\n

    This will again open an interactive prompt, requiring you to enter the information of the user registered on this Solid server for which you want to create the token: 

    ? Token name        bobs-auth-token\n? Pod baseuri       http://localhost:3000/\n? User email        bob@test.edu\n? User password     bobIsTheBest123\n? Token location    .tokens/.bobs-auth-token\n

    You just succesfully created a Client Credentials token for Bob! You can inspect the newly created token using cat .tokens/.bobs-auth-token to verify this.

    This command can again be executed without an interactive prompt by providing values for all options: 

    bashlib-css create-token -v -b \"http://localhost:3000/\" -n carols-auth-token -e carol@test.edu -p carolIsTheBest123 -o .tokens/.carols-auth-token\n

    "},{"location":"tutorial/#authentication-options","title":"Authentication options","text":"

    The Bashlib-css module exposes a set of authentication options. These are however not exposed over the CLI interface, but are available in the Node.JS interface to use in your own Node.JS projects. The Bashlib-solid module makes use of these options to authenticate the user on the CLI.

    "},{"location":"tutorial/#bashlib-solid","title":"Bashlib-solid","text":"

    The Bashlib-solid module provides a set of functions to facilitate usage of and development for Solid from Node.JS and the CLI. The CLI interface for Bashlib-solid can be accessed here: 

    node bashlib/solid/bin/solid.js\n
    optional: You can create an alias for this path so you do not have to write the full command every time. From here on, I will assume the alias alias bashlib-solid=\"node bashlib/solid/bin/solid.js\" to be set!

    "},{"location":"tutorial/#authentication","title":"Authentication","text":"

    Authentication in the Bashlib-solid module is done using the authentication options exposed by the Bashlib-css module. We will quickly go over the available authentication options:

    "},{"location":"tutorial/#authenticate-using-client-credentials-token","title":"Authenticate using Client Credentials token","text":"

    compatbility: CSSv4 - current We can now use the client credentials token we made in the previous step to authenticate our user from the CLI. We can do this using the following authentication options: 

     bashlib-solid --auth token <command> [options]\n
    Your identity provider is stored together with the token on your local filesystem, and does not have to be provided explicitly anymore.

    We can now use the authenticated fetch command on private resources: 

      bashlib-solid --auth token -t .tokens/.bobs-auth-token fetch http://localhost:3000/bob/profile/\n

    note: This method of authentication is restricted to pods hosted on a Community Solid Server instance of v4.0.0 and later. If you have another provider, please use the interactive login option described below.

    "},{"location":"tutorial/#interactive-authentication","title":"Interactive authentication","text":"

    compatbility: all

    An alternative authentication method is the interactive login. This option provides the default Inrupt Node.JS authentication flow, and is compatible with all pods. The interactive authentication requires the user to manually authenticate using their browser. 

     bashlib-solid --auth interactive --idp http://localhost:3000 <command> [options]\n
    We can now use the authenticated fetch command on private resources: 
      bashlib-solid --auth interactive --idp http://localhost:3000 fetch http://localhost:3000/bob/profile/\n

    "},{"location":"tutorial/#no-authentication","title":"No authentication","text":"

    compatbility: all

    Finally, you can just make use of the library without authenticating yourself. This is the default option when no auth option is specified. 

     bashlib-solid --auth none  <command> [options]\n
    We can now use fetch public resources as such: 
      bashlib-solid --auth none fetch http://localhost:3000/bob/profile/card\n

    "},{"location":"tutorial/#commands","title":"Commands","text":"

    Now that we have created a Solid account and pod and learned how to authenticate, we will look at the available commands in Bashlib-solid. In this section, we will do a runthrough for all available commands, and how they can be used. These commands will help you see solid not only as a Web technology, but as something you can easily include in existing workflows, while enabling ease of access and sharing of resources in between systems and users. We use the alias alias bashlib-auth = \"node bashlib/solid/bin/solid.js --auth token -t .tokens/.bobs-auth-token\" as a shortcut to make authenticated requests from here. In case you use another authentication method feel free to choose your own alias!

    "},{"location":"tutorial/#url-prefixes","title":"URL Prefixes","text":"

    All commands support URL prefixes for all URL parameters. Prefixes only work when the user is authenticated! Accepted prefixes are: - webid: - The user WebID - inbox: - The user inbox (if available) - root: - The user storage root (only found if the WebID is inside te data pod) - base: - Identical to root:

    For our user bob, we can now write the following url 

      base:/public/resource1.ttl\n
    to define the resource located at 
      http://localhost:3000/bob/public/resource1.ttl\n
    From here on out, we will make use of the prefixes, so feel free to authenticate with your own data pod, and follow the steps on your own pod environment.

    "},{"location":"tutorial/#fetch-cat","title":"fetch / cat","text":"

    The first command is the fetch command, with its twin the cat command. Both commands have an identical result, of fetching and displaying the remote resource to stdout, but the fetch command can take additional flags to pass custom headers and more.

    To fetch the user webId, we can now call the following function: 

      bashlib-auth fetch webid:\n
    As the authenticated user is Bob (see the alias we created), we just fetched bob's WebID. Additional options can be found by calling the help function. 
      bashlib-auth fetch --help\n
    If we want to fetch the file in an other RDF format, we can add custom headers: 
      bashlib-auth fetch -h \"Accept: application/ld+json\" webid:\n

    "},{"location":"tutorial/#list-ls","title":"list / ls","text":"

    The list or ls command displays a listing of a container on a Solid pod. The url argument should end in a / as it must be a container. Options can be discovered using the help command.

    To list the resources in our profile folder, we use the following command: 

      bashlib-auth ls base:/profile/\n

    By looking at the help function, we now will add the --all flag to also include any .acl files in the directory, and the --long flag to show a table overview of the result

      bashlib-auth ls --all --long base:/profile/\n
    "},{"location":"tutorial/#copy-cp","title":"copy / cp","text":"

    The copy or cp command copies resources form and to both the local filesystem and a data pod. Make sure you have read permissisons for the source location and write permissions for the destination location when they are on a pod.

    We will demonstrate the copy command by uploading a profile image form our local disk. If you have chosen a local image file, we can now upload this to our pod as follows: 

     bashlib-auth cp contacts.ttl base:/profile/\n
    This copies the contacts.ttl file to the container at the url http://localhost:3000/bob/profile/, and creates the contacts.ttl resource in this container. We can now request the copied file as follows: 
     bashlib-auth cat base:/profile/contacts.ttl\n
    We can also copy resources from one location on our pod to another location as follows: 
     bashlib-auth cp base:/profile/contacts.ttl base:/test/\n
    and can now fetch the resource at the target location 
     bashlib-auth fetch base:/test/contacts.ttl\n
    We see that the missing containers were automatically created.

    Notes: - Directories are always copied recursively as a default. - Copying files without an extension from the data pod will result in $., with the extension value based on the file contenttype. - Copying a file card$.ttl to your data pod will result in a file card with a content type of text/turtle. - Copying a file to a directory will place that file with the given filename in the destination directory. - When directly copying an .acl file, the --all flag must not be set. - Missing containers are automatically created."},{"location":"tutorial/#move-mv","title":"move / mv","text":"

    The move or mv command moves resources between different locations on a data pod or between data pods. It is equal to a cp operation followed by a rm operation on the source. Make sure that the correct permissions are set to read and remove the source resources, and write to the destination resources.

    In the last section, we made a contacts.ttl resource in our base:/test/ container. We can now move the test resource we just made as a demonstration: 

    bashlib-auth mv base:/test/contacts.ttl base:/test/demo_contacts.ttl\n

    "},{"location":"tutorial/#remove-rm","title":"remove / rm","text":"

    The remove or rm command removes resources from a data pod.

    With this command, we can now remove the demo_contacts.ttl file in the /test folder: 

    bashlib-auth rm base:/test/demo_contacts.ttl\n
    If we now look at the container listing: 
    bashlib-auth ls base:/test/\n
    we see that the resource has been removed. We can also remove the container now as follows: 
    bashlib-auth rm base:/test/\n
    To remove a container together with the contained resources, the -r, --recursive flag has to be set.

    "},{"location":"tutorial/#mkdir","title":"mkdir","text":"

    The mkdir command creates a target container.

    bashlib-auth mkdir base:/Pictures/\n
    creates a new Pictures/ container in the root of your pod.

    "},{"location":"tutorial/#touch","title":"touch","text":"

    The touch command creates a target resource in a container.

    bashlib-auth touch base:/test.txt\n
    creates a new resource test.txt in the root of your pod.

    "},{"location":"tutorial/#find","title":"find","text":"

    The find command enables you to find specific files in a given container based on a given filename regex.

    If we want to find where our profile card is located on our data pod, we can use the following command: 

    bashlib find --full base: card\n
    This command looks to match all found files in the base: container with the given filename match card. We use the --full flag to match with and display the full url of the found resources.

    "},{"location":"tutorial/#query","title":"query","text":"

    The query command is a convenience command that lets the user query one file or all files in a container based on a given SPARQL query.

    To return all triples from our WebID, we can use the following command: 

    bashlib-auth query webid: \"Select * WHERE { ?s ?p ?o . }\"\n

    This command also works on containers to recursively query all contained resources. To test this, we first make a new file containing a SPARQL query: 

    echo \"Select * WHERE { ?s ?p ?o . }\" > queryFile.txt\n
    Now, we can use this query to get all triples of all files on our data pod. We use the --pretty flag to receive the results in a table format: 
    bashlib-auth query -q -p base: queryFile.txt\n

    "},{"location":"tutorial/#perms","title":"perms","text":"

    The perms command provides three operations to list, edit and delete permissions for a resource on a Solid pod. This command only works for pods implementing the WAC protocols. Pods implementing the ACP protocol (Inrupt) are currently not supported.

    listing

    To list the permissions of your profile resource, we can use the following command: 

    bashlib-auth perms list webid:\n
    Here, we see the permissions written out for all agents, groups and the public for the given resource. This also works for containers. The following command prints the permissions of the pod root in a table format: 
    bashlib-auth perms list --pretty base:\n

    editing note: The editing of permissions for containers and other resources is exactly the same.

    To demonstrate the editing of permissions, we will first create a Private and Public folder on our pod. 

    bashlib-auth mkdir base:/Private/\nbashlib-auth mkdir base:/Public/\n

    We start by setting the permissions for the base:/Public/ container to be publicly readable, and make this the default for all contained resources (only an option for WAC). 

    bashlib-auth perms edit base:/Public/ p=rd\n

    When we now list the resource permissions, we see that public permissions are set to read and default. 

    bashlib-auth perms list --pretty base:/Public/\n

    Now we want to make sure the public cannot read or interact in any way with out Private container. For this we set public permissions to be nothing. However, we want our currently authenticated user to have full permissions in this container and all contained resources as a default (append permissions are implicitly set by giving write permissions): 

    bashlib-auth perms edit base:/Private/ p= u=rwcd\n

    When we now list the resource permissions, we see that no public permissions are set. We also see that the permissions are NOT inherited, meaning they are have been set for the resource successfully. 

    bashlib-auth perms list --pretty base:/Private/\n

    Finally, we want to give permission to our friend with the WebID https://my.friends.pod/profile/card#me to read and write in our Private container. For this we use the following command: 

    bashlib-auth perms edit base:/Private/ https://my.friends.pod/profile/card#me=rw\n

    When we now list the resource permissions, we see that our friend https://my.friends.pod/profile/card#me had received read, write and append (implicitly given through write) permissions over our Private container. 

    bashlib-auth perms list --pretty base:/Private/\n

    deleting Finally, we can also delete resource permissions. We can remove the permissions set for a given resource.

    To remove the permissions set for the public container, we can use the following command: 

    bashlib-auth perms delete base:/Public/\n

    If we now list the permissions for this container, we see that all current permissions are inherited from the parent container, as the permissions for the Public container have been deleted. 

    bashlib-auth perms list --pretty base:/Public/\n

    "},{"location":"tutorial/#edit","title":"edit","text":"

    The edit command is a helper command to quickly allow you to edit resources on your pod. The command takes the url of a resource (cannot be a container), copies the resource to your local filesystem and opens the resource with your given or your default editor.

    We will now edit the file base:/Public/test.txt with our local vim editor. If you do not have vim installed, please select your prefered editor or do not use the flag to use the default system editor. Using the --touch flag, we will create a new file if the resource does not exist yet. 

    bashlib-auth edit --editor vim --touch base:/Public/test.txt\n

    Now your editor will open with an empty file. You can now edit the file to contain a string of text, and then save the file in your editor. On exiting the editor, and returning to the terminal, you must press any button to continue. Now, the edited resource will be copied from your local filesystem to its location on the data pod, and be removed from the local filesystem.

    If we now look at the created file 

    bashlib-auth cat base:/Public/test.txt\n
    we see that the file has been created and contains the text that was written in the editor.

    "},{"location":"tutorial/#examples","title":"Examples","text":"

    In this section, we will go over some quick examples of how the CLI interface of Bashlib can be used to do some common tasks. For all examples, we will make use of the following aliases:

    • bashlib-css - alias bashlib-css=\"node bashlib/css/bin/css.js\"
    • bashlib-solid - alias bashlib-auth=\"node bashlib/solid/bin/solid.js\"
    • bashlib-auth - alias bashlib-auth=\"node bashlib/solid/bin/solid.js\" --auth <your_preferred_auth_option>
    "},{"location":"tutorial/#creating-a-new-pod-and-authentication-token","title":"Creating a new pod and authentication token","text":"

    compatibility CSSv4 - current

    First, we need to have a Community Solid Server instance running. More info on how to setup a Community Solid Server can be found here.

    First, we create a new pod on our running CSS instance. For this we run the create-pod command: 

    bashlib-css create-pod \n
    and we fill in the required information: 
    ? CSS instance base url   your CSS server baseURL, e.g. http://localhost:3000/\n? Pod and user name       the name for your pod\n? User email              the email address to login to the pod\n? User password           the password to login to the pod\n

    On completion, you will receive the following message 

    Pod for <name> created succesfully on <baseurl>/<name>/profile/card#me\n
    This <baseurl>/<name>/profile/card#me is the WebID of your newly created Solid account.

    Now that we have created a Solid account, we will create an authentication token we can use to authenticate to our pod from the CLI. For this, we use the create-token command. 

    bashlib-css create-token\n
    and fill in the required information: 
    ? Token name        the name of the token e.g. my-cli-auth-token\n? Pod baseuri       your CSS server baseURL, e.g. http://localhost:3000/\n? User email        the email address to login to the pod\n? User password     the password to login to the pod\n? Token location    you can choose a custom location or leave this blank to default to ~/.solid/.css-auth-token\n

    This creates a client-credentials-token you can use to authenticate at the Token location (default is ~/.solid/.css-auth-token). With this token, we can now authenticate our commands, such as listing the permissions of our WebID profile resource.

    In case the default location was used to store the token, we use the following command 

    bashlib-solid --auth \"token\" perms list --pretty webid:\n
    In case a custom token location was given, we pass the -t flag to indicate where the token can be found: 
    bashlib-solid --auth \"token\" -t <path_to_token> perms list --pretty webid:\n

    You can alias this to have a quick and easy way to use Bashlib from the cli (-t option only required if the default storage location was not used): 

    alias bashlib-auth=`bashlib-solid --auth \"token\" -t <path_to_token>\n
    From here on, you can use this alias to make all your commands authenticated: 
    bashlib-auth perms list --pretty webid:\n

    "},{"location":"tutorial/#setting-up-a-profile-image-on-your-pod","title":"Setting up a profile image on your pod","text":"

    Here we will discuss how we can quickly add a profile image to our profile, and store it on our pod. For this, we first need to choose a profile image. Say we have a nice image we want to use for this at ~/Pictures/my_nice_picture.png.

    First, we copy the image to our pod at the location base:/profile/img.png. 

    bashlib-auth cp ~/Pictures/my_nice_picture.png base:/profile/img.png\n

    Next, we will make this image publicly readable, so everyone can see your profile picture. If you do not like this, feel free to only add read permissions for specific WebIDs. 

    bashlib-auth perms edit base:/profile/img.png p=r\n

    With our image uploaded to our pod and made public, we will now have to edit our profile document to link the new profile image to our WebID. 

    bashlib-auth edit webId:\n
    This will open our profile document in our default editor. We now add the following line to the document (replace imageurl with the url of the newly uploaded image): 
    <#me> <http://xmlns.com/foaf/0.1/img> <imageurl> .\n

    Now save the document, and exit the editor. Press on any key to continue, and your profile document is now updated with a link to your newly added profile image

    Congratulations, you just set your profile image.

    "},{"location":"contributing/making-changes/","title":"Pull Requests","text":""},{"location":"documentation/overview/","title":"Overview Usage","text":""},{"location":"documentation/cli/access/","title":"Access Management","text":"

    The access command is used to manage access of resources on a Solid pod. Solid has two competing authorization proposals, Web Access Controls that use .acl resources, and Access Control Policies that use .acp resources.

    Bashlib implements full support for the management of WAC resources, and partial support for the management of ACP resources using the Inrupt universalAccess libraries. The access command has thee subcommands: list, set and delete

    "},{"location":"documentation/cli/access/#list","title":"List","text":"

    The list subcommand provides a listing of all access information for the targeted (container) resource.

    "},{"location":"documentation/cli/access/#arguments","title":"arguments","text":"

    Arguments:\n  url            Resource URL\n
    The url argument is the target (container) resource for which access is to be listed.

    "},{"location":"documentation/cli/access/#options","title":"options","text":"

    Options:\n  --acl          Displays ACL specific information such as group and default access\n  -p, --pretty   Pretty format\n  -v, --verbose  Log all operations\n
    The --acl option displays information specific to .acl resources, such as default access indicating that the authorization is also enforced on child resources without their own .acl file or inhereted access indicating that the access rules are derived from the default access of a parent resource. The --pretty option outputs the information in a table format The --verbose option outputs operation logs.

    "},{"location":"documentation/cli/access/#examples","title":"examples","text":"

    List the pod root access in a pretty format 

    sld access list --pretty https://mypod.org/\n

    "},{"location":"documentation/cli/access/#set","title":"Set","text":"

    The set subcommand is used to edit resource access.

    "},{"location":"documentation/cli/access/#arguments_1","title":"arguments","text":"

    Arguments:\n  url            Resource URL\n  permissions    Permission format when setting permissions. \n        Format according to id=[a][c][r][w]. \n        For public permissions please set id to \"p\". \n        For the current authenticated user please set id to \"u\".\n        For specific agents, set id to be the agent webid.\n
    The url argument is the target (container) resource for editing access rules. The permissions argument is a formatted string containing the identifier for which rules are defined, and the associated permissions that are to be set for the given identifier. Using p as the identifier targets public permissions and using u as the identifier targets the current WebID of the authenticated Bashlib session. The a is append rights, allowing PATCH operations to be made. The c is control rights, allowing the editing of access controls for a resource (for ACP this includes both readControl and writeControl) The r is read rights, allowing a GET request to a resource. The p is write rights. For a resource this allows it to be overwritten using a PUT request. For a container this allows resources to be added using both PUT and POST requests.

    "},{"location":"documentation/cli/access/#options_1","title":"options","text":"

    Options:\n  --acl          Enables ACL specific operations --default and --group\n  --default      Set the defined permissions as default (only in --acl mode)\n  --group        Process identifier as a group identifier (only in --acl mode)\n  -v, --verbose  Log all operations\n  -h, --help     display help for command\n
    The --acl option enables the default and group flags to be used, which are WAC specific operations. The --default option makes the current access rules default for all children resources when defined on a container. Only available in --acl mode. The --group option indicates that the identifier represents a group identifier. Only available in --acl mode. The --verbose option outputs operation logs.

    "},{"location":"documentation/cli/access/#examples_1","title":"examples","text":"

    Setting public read permissions for a resource 

    sld access set https://mypod.org/resource p=r\n

    Giving access to alice to write to a container 

    sld access set http://mypod.org/container/ http://people.org/alice/webid=w\n

    "},{"location":"documentation/cli/access/#delete","title":"Delete","text":"

    The delete subcommand is only available for WAC based pods using .acl resources. Note that removing a resource using the rm command also removes the associated .acl resource on the CSS automatically.

    "},{"location":"documentation/cli/access/#arguments_2","title":"arguments","text":"

    Arguments:\n  url            Resource URL\n
    The url argument is the target .acl resource that will be deleted.

    "},{"location":"documentation/cli/access/#options_2","title":"options","text":"

    Options:\n  -v, --verbose  Log all operations\n
    The --verbose option output operation logs.

    "},{"location":"documentation/cli/access/#example","title":"example","text":"

    Removing an acl resource. 

    sld access remove https://mypod.org/resource.acl\n

    "},{"location":"documentation/cli/access/#examples_2","title":"examples","text":""},{"location":"documentation/cli/aliases/","title":"Using aliases","text":"

    The current implementation of using aliases is weak, and may be changed in subsequent releases. Alias management is a potential future addition.

    "},{"location":"documentation/cli/aliases/#base","title":"Base","text":"

    The base: alias indicates the root of your Solid pod. Executing a command using this alias will target the root of your pod, if it is known. This value is taken from the pim:storage triple in the WebID. In case multiple storage locations are available, results in using this may be inconsistent. The following command wil make a listing of the root of the Solid pod of the current user. 

    sld ls base:/\n

    "},{"location":"documentation/cli/aliases/#webid","title":"WebID","text":"

    The webid: alias will target the user WebID. The following command wil retrieve the user WebID. 

    sld curl webid:\n

    "},{"location":"documentation/cli/aliases/#inbox","title":"Inbox","text":"

    The inbox: alias targets the user inbox, if known. This value is taken from the ldp:inbox triple in the WebID. The following command queries the inbox for events 

    sld query inbox:/ \"Select ?event where { ?event a <http://example.org/Event> }\n

    "},{"location":"documentation/cli/commands/","title":"Commands","text":"

    Bashlib provides a set of commands to manage resources and containers on your Solid pod. All examples make use of the abstraction sld as an alias for node bin/solid.js, and for all example we expect the user to be authenticated as documented in the Authentication section.

    "},{"location":"documentation/cli/commands/#curl","title":"Curl","text":"

    The curl command wraps the internal authenticated fetch function with functionality that mimics the curl command found on most linux shells.

    "},{"location":"documentation/cli/commands/#arguments","title":"arguments","text":"

    Arguments:\n  url                    file to be fetched\n
    The url argument for this command is the URL of the resource that is the target of the curl command.

    "},{"location":"documentation/cli/commands/#options","title":"options","text":"

    Options:\n  -v, --verbose          Write out full response and all headers\n  -H, --only-headers     Only write out headers\n  -m, --method <string>  GET, POST, PUT, DELETE, ...\n  -b, --body <string>    The request body\n  -F, --file <string>    File containing the request body. Ignored when the --body flag is set.\n  -h, --header <string>  The request header. Multiple headers can be added separately. e.g. -h \"Accept: application/json\" -h \"...\"\n
    The --verbose option writes out all response headers for a request. The --only-headers option only writes out response headers and ignores the response body. The --method option sets the HTTP request method. The --body option sets the HTTP request body. The --file option allows passing the file contents as the body of the request. The --header option allows the setting of a request header. Setting multiple headers requires multiple --header options to be set.

    "},{"location":"documentation/cli/commands/#examples","title":"examples","text":"

    A simple fetch request to a resource requesting a JSON-LD format 

    sld curl https://mypod.org/resource --header \"Accept: application/ld+json\"\n

    A POST request using a file contents as request body 

    sld curl -m POST -f /path/to/file https://mypod.org/resource\n

    "},{"location":"documentation/cli/commands/#list","title":"List","text":"

    The ls command provides the listing of a container on a Solid pod.

    "},{"location":"documentation/cli/commands/#arguments_1","title":"arguments","text":"

    Arguments:\n  url            URL of container to be listed\n
    The url argument for this command is the URL of the container for which a listing is to be made. This will only work if the url targets a container. It is important to add the trailing slash of the container URL!

    "},{"location":"documentation/cli/commands/#options_1","title":"options","text":"

    Options:\n  -a, --all      List all files including acl files\n  -f, --full     List files with their full uri\n  -l, --long     List in long format\n  -v, --verbose  \n
    The --all option includes .meta, .acl and .acp files in the listing. The --full option writes full resource URIs, not only the resource name. The --long option writes the listing in a table format, including available information about size, latest modification, related metadata resource and related acl resource. The --verbose option shows warnings.

    "},{"location":"documentation/cli/commands/#examples_1","title":"examples","text":"

    A listing of a container 

    sld ls https://mypod.org/container/\n

    A listing of a container showing all resources in a long format 

    sld ls --long --all https://mypod.org/container/\n

    "},{"location":"documentation/cli/commands/#copy","title":"Copy","text":"

    The cp command can copy resources between Solid pod locations, across Solid pods, or between the local file system and a Solid pod. If the source location is a container or directory, it will recursively copy the container and all sub-containers recursively copying the whole underlying resource tree, including empty containers.

    The default copying behavior ignores .meta, .acl and .acp resources, which can be changed using the --all flag. The default behavior is to overwrite files, the --interactive-override and --no-override options provide alternative behaviors.

    "},{"location":"documentation/cli/commands/#arguments_2","title":"arguments","text":"

    Arguments:\n  src                         file or directory to be copied\n  dst                         destination to copy file or directory to\n
    The src argument is the location of the resource or container to be moved. If the URL starts with http(s)://, the resource is assumed to be a remote resource, if not the resource is assumed to be local and matched with the local file system. The dst argument is the destination to which the source resource is to be copied. Similarly it uses the http(s):// prefix to decide if the location is local or remote. The default behavior ignores context resources such as .meta, .acl and .acp present in the directories. The --all flag ignores this behavior, though note that for authorization resources, as the target URIs are not edited, copying resources with these authorization resources does not imply they will result in the same access controls as the location they were copied from! The default behavior always automatically works recursively. At the moment this behavior cannot be altered.

    "},{"location":"documentation/cli/commands/#options_2","title":"options","text":"

    Options:\n  -a, --all                   Copy .acl files in recursive directory copies\n  -i, --interactive-override  Interactive confirmation prompt when overriding existing resource\n  -n, --no-override           Do not override existing files\n  -v, --verbose               Log all read and write operations\n
    The --all option includes .meta, .acl and .acp files in the listing. The --interactive-override option provides an interactive prompt when a copy will override an existing resource. The --no-override option ignores existing resources. The --verbose option shows warnings.

    "},{"location":"documentation/cli/commands/#examples_2","title":"examples","text":"

    Copying a local resource into a Solid pod container. 

    sld cp /path/to/file https://mypod.org/container/\n

    Copying a local resource to a specific remote resource 

    sld cp /path/to/file.ttl https://mypod.org/container/resource.ttl\n

    Copy the contents of container 1 of alice's pod to container 2 of bob's pod.

    sld cp https://mypod.org/alice/container1/. https://mypod.org/bob/container2/\n

    Copy the source container into the target container: https://mypod.org/bob/container2/container1/. 

    sld cp https://mypod.org/alice/container1/ https://mypod.org/bob/container2/\n

    Copy a resource from a solid pod to the local filesystem 

    sld cp https://mypod.org/container/resource.ttl ./resource.ttl\n

    "},{"location":"documentation/cli/commands/#move","title":"Move","text":"

    The mv command moves resources between Solid pod locations, across Solid pods, or between the local file system and a Solid pod. If the source location is a container or directory, it will recursively move the container and all sub-containers recursively copying the whole underlying resource tree, including empty containers. When moving from the local file system, files will not be deleted!

    The default copying behavior ignores .meta, .acl and .acp resources, which can be changed using the --all flag. The default behavior is to overwrite files, the --interactive-override and --no-override options provide alternative behaviors. The default behavior always automatically works recursively. At the moment this behavior cannot be altered.

    "},{"location":"documentation/cli/commands/#arguments_3","title":"arguments","text":"

    Arguments:\n  src                         file or directory to be moved\n  dst                         destination of the move\n
    The src argument is the location of the resource or container to be moved. If the URL starts with http(s)://, the resource is assumed to be a remote resource, if not the resource is assumed to be local and matched with the local file system. The dst argument is the destination to which the source resource is to be copied. Similarly it uses the http(s):// prefix to decide if the location is local or remote. The default behavior ignores context resources such as .meta, .acl and .acp present in the directories. The --all flag ignores this behavior, though note that for authorization resources, as the target URIs are not edited, copying resources with these authorization resources does not imply they will result in the same access controls as the location they were copied from!

    "},{"location":"documentation/cli/commands/#options_3","title":"options","text":"

    Options:\n  -a, --all                   Move .acl files when moving directories recursively\n  -i, --interactive-override  Interactive confirmation prompt when overriding existing files\n  -n, --no-override           Do not override existing files\n  -v, --verbose               Log all operations\n
    The --all option includes .meta, .acl and .acp files in the listing. The --interactive-override option provides an interactive prompt when a copy will override an existing resource. The --no-override option ignores existing resources. The --verbose option shows warnings.

    "},{"location":"documentation/cli/commands/#examples_3","title":"examples","text":"

    Moving a local resource into a Solid pod container. This does not remove the local resource! 

    sld mv /path/to/file https://mypod.org/container/\n

    Moving a local resource to a specific remote resource. This does not remove the local resource! 

    sld mv /path/to/file.ttl https://mypod.org/container/resource.ttl\n

    Move the contents of container1 into container2. This removes container 1.

    sld cp https://mypod.org/alice/container1/. https://mypod.org/bob/container2/\n

    Move the source container into the target container. 

    sld cp https://mypod.org/alice/container1/ https://mypod.org/bob/container2/container1/\n

    Move a resource from a solid pod to the local filesystem 

    sld cp https://mypod.org/container/resource.ttl ./resource.ttl\n

    "},{"location":"documentation/cli/commands/#remove","title":"Remove","text":"

    The rm command can remove resources and/or directories from a remote Solid pod.

    "},{"location":"documentation/cli/commands/#arguments_4","title":"arguments","text":"

    Arguments:\n  urls             URL of container to be listed\n
    The urls parameter accepts a sequence of urls that need to be removed.

    "},{"location":"documentation/cli/commands/#options_4","title":"options","text":"

    Options:\n  -r, --recursive  Recursively removes all files in given container (.acl files are removed on resource removal)\n  -v, --verbose    Log all operations\n
    The --recursive flag must be set when removing container resources. This automatically also removes any contained .acl, .acp and .meta resources. The --verbose flag outputs operation logs.

    "},{"location":"documentation/cli/commands/#examples_4","title":"examples","text":"

    Remove two resources 

    sld rm https://mypod.org/resource1 https://mypod.org/resource2\n

    Remove a container 

    sld rm https://mypod.org/container/\n

    "},{"location":"documentation/cli/commands/#mkdir","title":"Mkdir","text":"

    The mkdir command creates a new container on a remote Solid pod. The command automatically creates all parent directories that do not exist when specifying a subdirectory to create, and fails if the target container already exists.

    "},{"location":"documentation/cli/commands/#arguments_5","title":"arguments","text":"

    Arguments:\n  url            Container to start the search\n
    The url argument is the target container to be created.

    "},{"location":"documentation/cli/commands/#options_5","title":"options","text":"

    Options:\n  -v, --verbose  Log all operations\n
    The --verbose flag outputs operation logs.

    "},{"location":"documentation/cli/commands/#examples_5","title":"examples","text":"

    Create a new container 

    sld mkdir https://mypod.org/container/\n

    "},{"location":"documentation/cli/commands/#touch","title":"Touch","text":"

    The touch command creates an empty resource at the target location. This cannot create containers, for this use the mkdir command. The content type of the created resource is derived from the content type flag or if that is missing from the file extension. If neither can be found an error is thrown.

    "},{"location":"documentation/cli/commands/#arguments_6","title":"arguments","text":"

    Arguments:\n  url                          resource to be created\n
    The url argument is the target resource that is to be created.

    "},{"location":"documentation/cli/commands/#options_6","title":"options","text":"

    Options:\n  -c, --content-type <string>  Content type of the created resource\n  -v, --verbose                Log all operations\n
    the --content-type flag provides The --verbose flag outputs operation logs.

    "},{"location":"documentation/cli/commands/#examples_6","title":"examples","text":"

    Create a new resource 

    sld touch --content-type text/turtle https://mypod.org/container/resource\n

    "},{"location":"documentation/cli/commands/#tree","title":"Tree","text":"

    The tree command provides a tree-structured listing of the target container and all its subcontainers.

    "},{"location":"documentation/cli/commands/#arguments_7","title":"arguments","text":"

    Arguments:\n  url            Base container to construct tree over\n
    The url argument is the target container for which the tree listing is to be made.

    "},{"location":"documentation/cli/commands/#options_7","title":"options","text":"

    Options:\n  -a, --all      Display .acl, .acp and .meta resources\n  -f, --full     Display full resource URIs\n  -v, --verbose  Log all operations\n
    The --all flag includes the .acl, .acp and .meta context resources in the command output. The --full flag displays the resulting resources using their full URIs The --verbose flag outputs operation logs.

    "},{"location":"documentation/cli/commands/#examples_7","title":"examples","text":"

    Create tree listing on the root of a Solid pod. 

    sld tree https://mypod.org/\n

    "},{"location":"documentation/cli/commands/#find","title":"Find","text":"

    The find command can be used to find resources based on their name.

    "},{"location":"documentation/cli/commands/#arguments_8","title":"arguments","text":"

    Arguments:\n  url            Container to start the search\n  filename       Filename to match, processed as RegExp(filename)\n
    The url parameter is the container that forms the root of the resource tree in which the search is executed. The filename parameter is the filename to match, processed as a javascript RegExp.

    "},{"location":"documentation/cli/commands/#options_8","title":"options","text":"

    Options:\n  -a, --all      Match .acl, .acp and .meta files\n  -f, --full     Match full filename.\n  -v, --verbose  Log all operations\n
    The --all flag also matches access control and metadata files. The --full flag matches on and returns the full URIs of resources. The --verbose flag outputs operation logs.

    "},{"location":"documentation/cli/commands/#examples_8","title":"examples","text":"

    Find a resource named card in the profile/ container. 

    sld find http://mypod.org/profile/ card\n

    "},{"location":"documentation/cli/commands/#query","title":"Query","text":"

    The query command executes a SPARQL query over a target resource or container. In case a container is queried, all contained resources and subcontainers are recursively queried as well. The query itself is not federated, each query is individually evaluated over every resource. The following resources are included when querying: .ttl, .trig .nt, .nq, .jsonld, .rdf both on their resource extensions and their content type.. The Comunica engine is used for query evaluation. Note that only SELECT queries are supported!

    "},{"location":"documentation/cli/commands/#arguments_9","title":"arguments","text":"

    Arguments:\n  url              Resource to query. In case of container recursively queries all contained files.\n  query            SPARQL query string | file path containing SPARQL query when -q flag is active\n
    The url argument is the target resource or container to query. Containers are queried recursively on all contained resources in its resource tree. The query argument is either a SPARQL query in quotes, or the path to a file containing a sparql query if the --queryfile flag has been set.

    "},{"location":"documentation/cli/commands/#options_9","title":"options","text":"

    Options:\n  -a, --all        Match .acl and .meta files\n  -q, --queryfile  Process query parameter as file path of SPARQL query\n  -p, --pretty     Pretty format\n  -f, --full       Return containing files using full filename.\n  -v, --verbose    Log all operations\n
    The --all flag includes .acl, .acp and .meta resources in the query targets. The --queryfile flag changes the query argument to a file path for a resource containing a SPARQL query. The --pretty flag outputs the results in a table. The --full flag gives the full resource URIs of where the matches were found. The --verbose outputs operation logs.

    "},{"location":"documentation/cli/commands/#examples_9","title":"examples","text":"

    Evaluating a federated query over all resources in the profile container to look for entites with a given name. 

    sld query https://mypod.org/profile/ \"select ?entity ?name where { ?entity foaf:name ?name }\" --federated \n

    Evaluating a query stored in a local resource over the resources in the profile container individually, including .acl, .acp and .meta resources. 

    sld query --queryfile https://mypod.org/profile/ /path/to/sparql_query_file --all\n

    "},{"location":"documentation/cli/commands/#edit","title":"Edit","text":"

    The edit command enables the editing of remote resources using a local editor. The command will remain in standby until changes are saved, after which pressing a button in the shell will upload the resource to the Solid pod.

    Note: there currently is still a bug for longer edits, where saving the changes when a client session has expired will not be able to save the resource back to the pod. This should not be a problem when using client credentials.

    "},{"location":"documentation/cli/commands/#arguments_10","title":"arguments","text":"

    Arguments:\n  url                                       Resource URL\n
    The url argument is target resource that will be edited.

    "},{"location":"documentation/cli/commands/#options_10","title":"options","text":"

    Options:\n  -e, --editor <path_to_editor_executable>  Use custom editor\n  -t, --touch                               Create file if not exists\n  -v, --verbose                             Log all operations\n
    The --editor option enables the use of a specific local editor to modify the resource. The --touch option will create the resource if it does not exist yet. The --verbose option outputs operation logs.

    "},{"location":"documentation/cli/commands/#examples_10","title":"examples","text":"

    Editing a resource using the default editor. 

    sld edit https://mypod.org/resource1\n

    Creating and editing a resource using vs-code (code) 

    sld edit --touch --editor code  https://mypod.org/non_existing_resource\n

    "},{"location":"documentation/cli/commands/#access","title":"Access","text":"

    The access command is used to manage resource access. This is explained in the access management section.

    "},{"location":"documentation/cli/commands/#auth","title":"Auth","text":"

    The auth command is used to manage authentication in Bashlib. This is explained in the authentication management section.

    "},{"location":"documentation/cli/overview/","title":"Overview Usage for CLI","text":"

    The command line interface provides a set of basic interactions to work with the resources on a Solid pod.

    Introduce Authentication

    Introduce Commands

    Introduce Shortcuts

    "},{"location":"documentation/typescript/css-specific/","title":"css specific typescript","text":""},{"location":"documentation/typescript/example-requests/","title":"Example requests ts","text":""},{"location":"documentation/typescript/metadata/","title":"Handling metadata","text":""},{"location":"documentation/typescript/overview/","title":"Overview Usage for Typescript","text":""}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Welcome","text":"

    Welcome to the Bashlib Homepage.

    Bashlib is a Command Line Interface for working with Solid Pods, made by Ruben Dedecker at the KNoWS team at Ghent University.

    An introduction to quickly setting up a Community Solid Server instance and interfacing with it using Bashlib is found in the tutorial section.

    Documentation on the tool and the available commands is found in the documentation section.

    Documentation may be incomplete in content and structure. Feel free to open a discussion and report incorrect information.

    "},{"location":"tutorial/","title":"Bashlib Tutorial","text":"

    This tutorial provides a quick setup of a Community Solid Server, and some useful interactions to manage resources on a created Solid pod.

    "},{"location":"tutorial/#setting-up-a-solid-server","title":"Setting up a Solid Server","text":"

    To use Bashlib, we first explain how to setup your own local Solid Server on which you can create your first Solid pod. In case you already have a Solid pod, feel free to skip this section. Alteratively, you may want to create a Solid pod on one of the free Pod provider services. Note that when using a free provider, if something goes wrong you might not be able to recover your data, or that service may be relatively slow, as there are free and community hosted. Additionally, only server running the Community Solid Server or Inrupt Enterprise Solid Server versions will be able to make client credentials to authenticate automatically without needing an interactive browser session. A free CSS hosting service can be found here. A free ESS hosting service can be found here.

    To setup your own local Community Solid Server, we make use in this tutorial of the Community Solid Server. The full tutorial can be found here. When you are done with the tutorial, you are free to remove the current folder to delete all created files!

    We use NPX to setup a CSS instance, and use a file config to store all data in the data/ folder. Ideally execute the tutorial in an empty directory, so afterwards you can remove all tutorial data by removing this directory! 

    npx @solid/community-server -c @css:config/file.json -f data/\n

    Congratulations! Your own CSS instance is now running on localhost on port 3000! Keep this shell open during the tutorial! You can confirm this by browsing to http://localhost:3000 in the browser, and you will be greeted with a setup screen.

    "},{"location":"tutorial/#creating-an-account","title":"Creating an account","text":"

    Now we will create an account and associated WebID on this local CSS instance. Navigating to http://localhost:3000 in the browser, and you will be greeted with a setup screen. Press the Sign up for an account link to create an account on this local CSS instance. As this is a local instance, the email does not really matter, as this is only used for authentication purposes and recovering a pod, but is never verified.

    For now, we make an example person Bob using his email bob@test.com and password bob. Next, we make a pod for this account by pressing the Create pod link! Here, we provide a pod name, for example mydatapod. Congratulations, you just created a new data pod at http://localhost:3000/mydatapod/ and associated WebID at http://localhost:3000/mydatapod/profile/card#me!

    "},{"location":"tutorial/#setting-up-bashlib","title":"Setting up Bashlib","text":"

    With our Solid pod and WebID created, now it is time to setup Bashlib! For a quick setup, we use NPX 

    npx solid-bashlib curl http://localhost:3000/mydatapod/profile/card#me\n
    which prompts to install bashlib, and on installation with show your WebID profile.

    Alternatively, a local setup can be cloned from github. 

    git clone https://github.com/SolidLabResearch/Bashlib.git\ncd Bashlib\nnpm install\nnpm run build;\n\nnode bin/solid.js curl http://localhost:3000/mydatapod/profile/card#me\n

    For the remainder of this tutorial, we will use sld as the alias for npx solid-bashlib.

    "},{"location":"tutorial/#managing-authentication","title":"Managing Authentication","text":"

    As Solid aims to provide secure online data management, working with secured resources requires users to be authenticated for the system to evaluate their access.

    The full documentation on the authentication options for bashlib can be found in the authentication management section.

    "},{"location":"tutorial/#executing-commands-without-authentication","title":"Executing commands without authentication","text":"

    To run commands over public data without any authentication, we can start bashlib with the --auth flag set to none to prevent it from automatically trying to authenticate requests. We can for example make an unauthenticated request to our created WebID as follows (WebID resources are always public): 

    sld --auth none curl --header \"Accept: application/n-triples\" http://localhost:3000/mydatapod/profile/card#me\n
    This creates unauthenticated fetch request to the WebID resource and outputs the result on the command line. As we passed a --header option that requests the result in an n-triples format, the returned data is formatted in an n-triples format.

    "},{"location":"tutorial/#setting-a-webid-and-interactive-authentication","title":"Setting a WebId and interactive authentication","text":"

    However, for most personal use resource operations will require the user to be authenticated. To start, we pass our created WebID to Bashlib. This can either be done using the interactive interface by running: 

    sld auth set\n
    and selecting the option: Authenticate using new WebID and providing your WebID here. Alternatively, the WebID option can be provided directly in the arguments as follows: 
    sld auth set http://localhost:3000/mydatapod/profile/card#me\n

    To see the WebID used by Bashlib to authenticate requests, we can run 

    sld auth show --pretty\n
    which shows us that our WebID is now used by bashlib to authenticate requests.

    However, now we've only told Bashlib our WebID, we have not yet given it the means to authenticate a request using this WebID. There are two options for authenticating with Bashlib to be able to make authenticated requests. We can use an interactive authentication flow that uses our browser to authenticate, or we can create a credentials token that we can store which will allow us to create authenticated requests directly without needing an interactive browser session.

    Per default, Bashlib will use a dynamic authentication approach, where it will first look if there is an active authenticated session it can reuse. If not, it will try to create a new session using any stored credentials token. If none can be found, it will open a browser window and have the user authenticate themselves interactively using the browser.

    To create a listing of the profile directory of our Solid pod, run the following command: 

    npx solid-bashlib ls base:/profile/\n
    This base: is an alias for our pod root (http://localhost:3000/mydatapod/), if it can be discovered from the user WebID. Upon running the command, a browser window will pop-up asking the user to authenticate themselves. Once logged in, looking back at the command line we see that a listing is displayed of the profile container, which is only visible to the user WebID, so the authentication was successful.

    Additionally, running the listing command again, we see that no authentication is required, as Bashlib stored the previous session, and reuses this session to authenticate subsequent requests made for the same WebID. 

    npx solid-bashlib ls base:/profile --pretty\n

    Looking at the current authentication status 

    sldv auth show --pretty\n
    we see that an active session is available now.

    "},{"location":"tutorial/#creating-a-credentials-token-to-automate-authentication","title":"Creating a credentials token to automate authentication","text":"

    However, having to authenticate interactions can be an overhead, especially if commands are to be executed automatically from a script. To automate the authentication flow, we need to make a token that will allow us to do an authentication flow that does not require a browser window.

    Currently the generation of credential tokens that can directly authenticate a user session is only provided by the Community Solid Server and the Enterprise Solid Server. Both implementations differ however. In this section we only address the creation of a token for the Community Solid Server. If you have a pod on an Enterprise Solid Server, you can follow the documentation for ESS token creation in the authentication section.

    To create the credentials token for our current WebID in Bashlib, we execute the following command: 

    sld auth create-token-css\n
    This will prompt us on if the token we want to create is for our currently logged in user. Press y to continue. Now we are prompted for our email (bob@test.com) and password (bob).

    To confirm the generation of our token, we run the show command again, which now indicates we have an auth token present. 

    npx solid-bashlib auth show --pretty\n
    From now on, after session expiration, new sessions will be automatically generated through this token without going through an interactive browser session.

    All authentication information is stored per default at ~/.solid/

    "},{"location":"tutorial/#managing-authorization","title":"Managing authorization","text":"

    Now that we have an authorized user, we can manage the authorization rules for the resources on our Solid pod. Note that Solid has two competing authorization systems. The Web Access Controls specification that uses .acl resources to manage resource access, and the Access Control Protocol that uses .acp resources to manage resource access.

    Bashlib implements two different access management regimes: It fully implements the WAC suite for listing and editing permissions and removing permission resources, and it implements the universal access suite that can work with both WAC and ACP access management systems. However this universal system is less expressive in its functionality. Bashlib will automatically detect the used access control mechanism, but enables additional functionality when working with pods hosted on a WAC-based Solid Server such as access propagation and identity groups.

    "},{"location":"tutorial/#listing-authorization","title":"Listing authorization","text":"

    To list the permissions set on the root of our pod, run: 

    sld access list --pretty base:/\n
    We see that our WebID has full permissions to read, write, append and control resources on our pod (deleting a resource requires write permissions). We also notice public read permissions on our root container, which we will change in the next section. If our pod is hosted on a WAC-based Solid Server (such as the Community Solid Server we setup above), we see the WebID permissions on our root are set as default, meaning they are enforced on all sub-containers and resources of this root container unless otherwise specified by these sub-containers or resources. Additionally, the inherited field shows if this authorization state is defined by an .acl file tied directly to the resource itself (in that case the value is no), or if it was derived of a default permissions set by one of the resource parents (in that case the value is yes).

    "},{"location":"tutorial/#editing-authorization","title":"Editing authorization","text":"

    As shown above, currently our pod root container is set to be publicly readable. To change these permissions, we set the public access rights to our root container to be nothing. When interacting pods hosted on a WAC-based Solid Server, we can use the --default flag to make these access rules the default, however as the default access defined by the system is no access, this makes no real difference in this case. To do this, we run the following command: 

    sld access set base:/ p=\n
    The base:/ value targets our pod root container. The p value sets the access target as public, and the empty space after the = symbol indicates that the permissions given to the public are none.

    We confirm this by listing the permissions again: 

    sld access list --pretty base:/\n
    showing public read permissions are not set anymore. Additionally, we see that a resource request to the full URI gives us a 401 Unauthenticated response. 
    sld --auth none curl http://localhost:3000/mydatapod/\n

    If we now want to create an inbox container, to which people can write resources but not read resources, we first make a new directory 

    sld mkdir base:/inbox/\n
    that we can confirm in our listing to exist now: 
    sld ls base:/\n

    Listing permissions for this created container, we see that no public permissions are set for this container. 

    sld access list --pretty base:/inbox/ \n

    Now, we set public read permissions for this resource: 

    sld access set base:/inbox/ p=w\n
    Listing permissions again shows that now only read permissions are assigned to this container. 
    sld access list --pretty base:/inbox/ \n

    Note that setting permissions for an identifier removes any existing permissions. Setting read permissions as follows 

    sld access set base:/inbox/ p=r\n
    will remove the existing write permission, as we did not renew it in this operation. 
    sld access list --pretty base:/inbox/ \n

    To give access to our contact to also read our inbox, we assign access rules for their WebID. 

    sld access set base:/inbox/ https://poeple.org/alice/webid=r\n
    Listing the permissions now we see Alice has been given read access to our inbox container.

    "},{"location":"tutorial/#requesting-and-querying-resources","title":"Requesting and querying resources","text":"

    In addition to authentication and authorization management, Bashlib provides a set of commands aimed at the requesting and querying of resources that we will go over here. The documentation for every command can be found here.

    The first command we have already touched upon is curl. It mimics the curl command provided by BASH and provides options for choosing the HTTP method, the body and more. Simply executing a curl on a URL performs a GET request. 

    sld curl base:/\n

    The next command we have seen before is the ls command. It outputs a listing of the targeted container, and can be made to include access control and metadata resources present in the container as well. 

    sld ls -la base:/\n

    The tree command allows us to create a directory tree starting from the targeted container. 

    sld tree base:/\n

    The cp command allows the copying of resources on the same pod, between pods, or from and to the local file system. It per default is fully recursive, and will copy the whole underlying resource tree to the target destination. 

    sld cp /path/to/img.png base:/images/img.png\n

    The mv command is similar to the copy command, but it removes the source resources after the move (except for when moving from the local file system). 

    sld mv base:/images/img.png base:/photos/.\n

    The rm command can be used to remove resources and containers from a Solid pod. It requires an explicit flag to work recursive. 

    sld rm -r base:/photos/\n

    The mkdir command creates an empty container on a Solid pod. 

    sld mkdir base:/documents/\n

    The touch command creates an empty resource 

    sld touch base:/documents/work/file.txt\n

    The find command searches all resources in the given container and its sub-containers for a name match. 

    sld find base:/ file.txt\n

    The find command evaluates a query over all resources in the given container and its sub-containers individually. The --federated flag can be used to evaluate the query over the combined knowledge graph of all found resources. 

    sld query --all base:/ \"Select ?person where { ?person <http://www.w3.org/1999/02/22-rdf-syntax-ns#type> <http://xmlns.com/foaf/0.1/Person> . }\" \n

    The edit command opens a remote resource in a local editor. It copies the resource to a temporary file, after which changes can be committed to this file. Upon pressing a button in the Bashlib program, this temporary file is synced again with the remote resource. 

    sld edit base:/documents/work/file.txt\n

    "},{"location":"tutorial/#setting-up-a-profile-image-on-your-pod","title":"Setting up a profile image on your pod","text":"

    Let's end with a concrete task, setting a profile picture. We choose our profile picture located at ~/Pictures/my_nice_picture.png.

    To start, we copy the image to our pod at the location base:/profile/img.png using the following command: 

    sld cp ~/Pictures/my_nice_picture.png base:/profile/img.png\n

    As profile pictures need to be publicly readable, so everyone can see your profile picture, we set public read permissions for this resource. 

    sld access set base:/profile/img.png p=r\n

    With our image uploaded to our pod and made public, we will now have to edit our profile document to link the new profile image to our WebID (use the --editor option to choose an alternative editor) 

    sld edit webId:\n
    This will open our profile document in our default editor (or our editor of choice). We now add the following line to the document (replace imageurl with the url of the newly uploaded image): 
    <http://localhost:3000/mydatapod/profile/card#me> <http://xmlns.com/foaf/0.1/img> <http://localhost:3000/mydatapod/profile/img.png> .\n

    Now save the document, and exit the editor. Press on any key to continue, and your profile document is now updated with a link to your newly added profile image

    Congratulations, you just set your profile image!

    If you were using a web-hosted Solid pod, you should be able to see your result when looking at your profile here. For locally hosted pods however, most likely your browser will stop you from looking at localhost links because of CORS errors.

    "},{"location":"contributing/making-changes/","title":"Pull Requests","text":""},{"location":"documentation/overview/","title":"Documentation Overview","text":"

    The Bashlib command line interface provides straightforward commands to interact with your Solid pod. It can be useful both for personal use, setting up small workflows or quick demonstrations of proof of concepts. The authentication options enable quick switching between WebIDs and Solid Pods. As not everything is optimized for performance, operations that target many resources or few but large resources may not be performant enough for some use-cases, as the internal resource management does not make use of streaming.

    To login and manage authentication info for Bashlib, navigate to the authentication management section. For an overview of the available commands, their options and code example, navigate to the available commands section. To view and manage access to resources, navigate to the access management section. To see how to use aliases to speed up your flow, navigate to the using aliases section.

    "},{"location":"documentation/cli/access/","title":"Access Management","text":"

    The access command is used to manage access of resources on a Solid pod. Solid has two competing authorization proposals, Web Access Controls that use .acl resources, and Access Control Policies that use .acp resources.

    Bashlib implements full support for the management of WAC resources, and partial support for the management of ACP resources using the Inrupt universalAccess libraries. The access command has thee subcommands: list, set and delete

    "},{"location":"documentation/cli/access/#list","title":"List","text":"

    The list subcommand provides a listing of all access information for the targeted (container) resource.

    "},{"location":"documentation/cli/access/#arguments","title":"arguments","text":"

    Arguments:\n  url            Resource URL\n
    The url argument is the target (container) resource for which access is to be listed.

    "},{"location":"documentation/cli/access/#options","title":"options","text":"

    Options:\n  --acl          Displays ACL specific information such as group and default access\n  -p, --pretty   Pretty format\n  -v, --verbose  Log all operations\n
    The --acl option displays information specific to .acl resources, such as default access indicating that the authorization is also enforced on child resources without their own .acl file or inhereted access indicating that the access rules are derived from the default access of a parent resource. The --pretty option outputs the information in a table format The --verbose option outputs operation logs.

    "},{"location":"documentation/cli/access/#examples","title":"examples","text":"

    List the pod root access in a pretty format 

    sld access list --pretty https://mypod.org/\n

    "},{"location":"documentation/cli/access/#set","title":"Set","text":"

    The set subcommand is used to edit resource access.

    "},{"location":"documentation/cli/access/#arguments_1","title":"arguments","text":"

    Arguments:\n  url            Resource URL\n  permissions    Permission format when setting permissions. \n        Format according to id=[a][c][r][w]. \n        For public permissions please set id to \"p\". \n        For the current authenticated user please set id to \"u\".\n        For specific agents, set id to be the agent webid.\n
    The url argument is the target (container) resource for editing access rules. The permissions argument is a formatted string containing the identifier for which rules are defined, and the associated permissions that are to be set for the given identifier. Using p as the identifier targets public permissions and using u as the identifier targets the current WebID of the authenticated Bashlib session. The a is append rights, allowing PATCH operations to be made. The c is control rights, allowing the editing of access controls for a resource (for ACP this includes both readControl and writeControl) The r is read rights, allowing a GET request to a resource. The p is write rights. For a resource this allows it to be overwritten using a PUT request. For a container this allows resources to be added using both PUT and POST requests.

    "},{"location":"documentation/cli/access/#options_1","title":"options","text":"

    Options:\n  --acl          Enables ACL specific operations --default and --group\n  --default      Set the defined permissions as default (only in --acl mode)\n  --group        Process identifier as a group identifier (only in --acl mode)\n  -v, --verbose  Log all operations\n  -h, --help     display help for command\n
    The --acl option enables the default and group flags to be used, which are WAC specific operations. The --default option makes the current access rules default for all children resources when defined on a container. Only available in --acl mode. The --group option indicates that the identifier represents a group identifier. Only available in --acl mode. The --verbose option outputs operation logs.

    "},{"location":"documentation/cli/access/#examples_1","title":"examples","text":"

    Setting public read permissions for a resource 

    sld access set https://mypod.org/resource p=r\n

    Giving access to alice to write to a container 

    sld access set http://mypod.org/container/ http://people.org/alice/webid=w\n

    "},{"location":"documentation/cli/access/#delete","title":"Delete","text":"

    The delete subcommand is only available for WAC based pods using .acl resources. Note that removing a resource using the rm command also removes the associated .acl resource on the CSS automatically.

    "},{"location":"documentation/cli/access/#arguments_2","title":"arguments","text":"

    Arguments:\n  url            Resource URL\n
    The url argument is the target .acl resource that will be deleted.

    "},{"location":"documentation/cli/access/#options_2","title":"options","text":"

    Options:\n  -v, --verbose  Log all operations\n
    The --verbose option output operation logs.

    "},{"location":"documentation/cli/access/#example","title":"example","text":"

    Removing an acl resource. 

    sld access remove https://mypod.org/resource.acl\n

    "},{"location":"documentation/cli/access/#examples_2","title":"examples","text":""},{"location":"documentation/cli/aliases/","title":"Using aliases","text":"

    The current implementation of using aliases is weak, and may be changed in subsequent releases. Alias management is a potential future addition.

    "},{"location":"documentation/cli/aliases/#base","title":"Base","text":"

    The base: alias indicates the root of your Solid pod. Executing a command using this alias will target the root of your pod, if it is known. This value is taken from the pim:storage triple in the WebID. In case multiple storage locations are available, results in using this may be inconsistent. The following command wil make a listing of the root of the Solid pod of the current user. 

    sld ls base:/\n

    "},{"location":"documentation/cli/aliases/#webid","title":"WebID","text":"

    The webid: alias will target the user WebID. The following command wil retrieve the user WebID. 

    sld curl webid:\n

    "},{"location":"documentation/cli/aliases/#inbox","title":"Inbox","text":"

    The inbox: alias targets the user inbox, if known. This value is taken from the ldp:inbox triple in the WebID. The following command queries the inbox for events 

    sld query inbox:/ \"Select ?event where { ?event a <http://example.org/Event> }\n

    "},{"location":"documentation/cli/authentication/","title":"Authentication Management","text":"

    The Bashlib CLI interface provides multiple options for authentication management. It enables interactive login flows using the browser, that work with any Solid pod server. Additionally, it includes the client credentials flow to generate authentication tokens without needing a browser login both for the Community Solid Server v7 and the Enterprise Solid Server from Inrupt.

    All examples make use of the abstraction sld as an alias for node bin/solid.js,

    "},{"location":"documentation/cli/authentication/#enforcing-specific-authorization-flows","title":"Enforcing specific authorization flows","text":"

    When setting up test flows on Solid, it might be interesting to force a specific authentication flows to be used. For this, the --auth option can be set on the bashlib program as such:] 

    sld --auth interactive\n
    This examples forces authentication via an interactive browser session. Other options are token for only token based authentication, none for no authentication and request to dynamically choose an authentication option during use, which is the default. The --port option can be changed to change the port of the local service that is setup to manage interactive authentication flows with the browser.

    "},{"location":"documentation/cli/authentication/#auth-command","title":"Auth command","text":"

    The auth command contains all functionality to manage authentication options and create client credentials tokens.

    "},{"location":"documentation/cli/authentication/#set","title":"Set","text":"

    The set subcommand is used to manage the authentication session for Bashlib. It provides the ability to set a specific WebID as an argument, or if no argument is given starts an interactive selection dialog to change the active WebID.

    "},{"location":"documentation/cli/authentication/#arguments","title":"arguments","text":"

    Arguments:\n  webid       Set active WebID directly, without requiring manual selection.\n
    The webid argument directly sets the session to the provided WebID value.

    "},{"location":"documentation/cli/authentication/#examples","title":"examples","text":"

    Interactive session management 

    sld auth set\n

    Setting a specific active WebID 

    sld auth set https://people.org/alice/webid\n

    "},{"location":"documentation/cli/authentication/#show","title":"Show","text":"

    The show subcommand shows the current authentication session. It shows the WebId, if there is an active authentication session and if a client credential token is available.

    "},{"location":"documentation/cli/authentication/#options","title":"options","text":"

    Options:\n  -p, --pretty  Show listing in table format.\n
    The --pretty option displays the result in a table formate.

    "},{"location":"documentation/cli/authentication/#examples_1","title":"examples","text":"
    sld auth show\n
    "},{"location":"documentation/cli/authentication/#clear","title":"Clear","text":"

    The clear subcommand clears the current authentication session and active WebID. It does not remove any stored authentication information.

    "},{"location":"documentation/cli/authentication/#examples_2","title":"examples","text":"
    sld auth clear\n
    "},{"location":"documentation/cli/authentication/#list","title":"List","text":"

    The list subcommand lists the stored authentication information. It shows the WebIds, if there is an active authentication session and if a client credential token is available.

    "},{"location":"documentation/cli/authentication/#options_1","title":"options","text":"

    Options:\n  -p, --pretty  Show listing in table format.\n
    The --pretty option displays the result in a table formate.

    "},{"location":"documentation/cli/authentication/#examples_3","title":"examples","text":"
    sld auth list\n
    "},{"location":"documentation/cli/authentication/#remove","title":"Remove","text":"

    The remove subcommand provides the ability to remove authentication information from Bashlib. It provides an interactive menu if no argument is given, or can remove information for specific WebIDs or all information directly via the CLI arguments.

    "},{"location":"documentation/cli/authentication/#arguments_1","title":"arguments","text":"

    Arguments:\n  string      webid | all\n
    The command has an optional parameter. When passing the argument string all, all authentication information is removed. Passing a specific WebID removes all authentication information tied to that WebID. If no argument is passed, an interactive CLI menu is provided.

    "},{"location":"documentation/cli/authentication/#examples_4","title":"examples","text":"

    Opening the interactive menu 

    sld auth remove\n

    Removing all authentication information 

    sld auth remove all\n

    Removing a specific WebID 

    sld auth remove https://people.org/alice/webid\n

    "},{"location":"documentation/cli/authentication/#create-token-css","title":"Create Token (CSS)","text":"

    The token creation is divided in two subcommands, one for the Community Solid Server and one for the Inrupt Enterprise Solid Server, as both have a different approach to token generation for client applications.

    The create-token-css command creates a client credentials token for pods hosted on a Community Solid Server version 7. The authentication options can be passed both as command line arguments, or in an interactive dialog if they are not provided through the CLI options. The interactive creation menu will ask to use the WebID of the current session to create a token when available.

    "},{"location":"documentation/cli/authentication/#options_2","title":"options","text":"

    Options:\n  -w, --webid <string>     User WebID\n  -n, --name <string>      Token name\n  -e, --email <string>     User email\n  -p, --password <string>  User password\n  -v, --verbose            Log actions\n  -h, --help               display help for command\n
    The --webid option is the WebID for which the token is created. The --name option is the name of the token (only important for token management). The --email option is the email that was used to create the account tied to the WebID. The --password option is the password tied to the account. the --verbose option outputs operation logs.

    "},{"location":"documentation/cli/authentication/#examples_5","title":"examples","text":"

    Open interactive dialog to create token 

    sld auth create-token-css\n

    "},{"location":"documentation/cli/authentication/#create-token-ess","title":"Create Token (ESS)","text":"

    The create-token-ess command creates a client credentials token for pods hosted on an Inrupt Enterprise Solid Server. The authentication options can be passed both as command line arguments, or in an interactive dialog if they are not provided through the CLI options. The interactive creation menu will ask to use the WebID of the current session to create a token when available. The Inrupt token generation relies on the registration of applications via their application registration service. After registering Bashlib, an id and secret value will be shown. These values need to be provided to this command to be able to automatically create authenticated sessions without needing interactive login.

    "},{"location":"documentation/cli/authentication/#options_3","title":"options","text":"

    Options:\n  -w, --webid <string>     User WebID\n  -i, --id <string>        application registration id\n  -s, --secret <string>    application registration secret\n  -v, --verbose            Log actions\n  -h, --help               display help for command\n
    The --webid option is the WebID for which the token is created. The --id option is the id value retrieved from the registration flow described above. The --secret option is the secret value retrieved from the registration flow described above. the --verbose option outputs operation logs.

    "},{"location":"documentation/cli/authentication/#examples_6","title":"examples","text":"

    Open interactive dialog to create token 

    sld auth create-token-ess\n

    "},{"location":"documentation/cli/commands/","title":"Commands","text":"

    Bashlib provides a set of commands to manage resources and containers on your Solid pod. All examples make use of the abstraction sld as an alias for node bin/solid.js, and for all example we expect the user to be authenticated as documented in the Authentication section.

    "},{"location":"documentation/cli/commands/#curl","title":"Curl","text":"

    The curl command wraps the internal authenticated fetch function with functionality that mimics the curl command found on most linux shells.

    "},{"location":"documentation/cli/commands/#arguments","title":"arguments","text":"

    Arguments:\n  url                    file to be fetched\n
    The url argument for this command is the URL of the resource that is the target of the curl command.

    "},{"location":"documentation/cli/commands/#options","title":"options","text":"

    Options:\n  -v, --verbose          Write out full response and all headers\n  -H, --only-headers     Only write out headers\n  -m, --method <string>  GET, POST, PUT, DELETE, ...\n  -b, --body <string>    The request body\n  -F, --file <string>    File containing the request body. Ignored when the --body flag is set.\n  -h, --header <string>  The request header. Multiple headers can be added separately. e.g. -h \"Accept: application/json\" -h \"...\"\n
    The --verbose option writes out all response headers for a request. The --only-headers option only writes out response headers and ignores the response body. The --method option sets the HTTP request method. The --body option sets the HTTP request body. The --file option allows passing the file contents as the body of the request. The --header option allows the setting of a request header. Setting multiple headers requires multiple --header options to be set.

    "},{"location":"documentation/cli/commands/#examples","title":"examples","text":"

    A simple fetch request to a resource requesting a JSON-LD format 

    sld curl https://mypod.org/resource --header \"Accept: application/ld+json\"\n

    A POST request using a file contents as request body 

    sld curl -m POST -f /path/to/file https://mypod.org/resource\n

    "},{"location":"documentation/cli/commands/#list","title":"List","text":"

    The ls command provides the listing of a container on a Solid pod.

    "},{"location":"documentation/cli/commands/#arguments_1","title":"arguments","text":"

    Arguments:\n  url            URL of container to be listed\n
    The url argument for this command is the URL of the container for which a listing is to be made. This will only work if the url targets a container. It is important to add the trailing slash of the container URL!

    "},{"location":"documentation/cli/commands/#options_1","title":"options","text":"

    Options:\n  -a, --all      List all files including acl files\n  -f, --full     List files with their full uri\n  -l, --long     List in long format\n  -v, --verbose  \n
    The --all option includes .meta, .acl and .acp files in the listing. The --full option writes full resource URIs, not only the resource name. The --long option writes the listing in a table format, including available information about size, latest modification, related metadata resource and related acl resource. The --verbose option shows warnings.

    "},{"location":"documentation/cli/commands/#examples_1","title":"examples","text":"

    A listing of a container 

    sld ls https://mypod.org/container/\n

    A listing of a container showing all resources in a long format 

    sld ls --long --all https://mypod.org/container/\n

    "},{"location":"documentation/cli/commands/#copy","title":"Copy","text":"

    The cp command can copy resources between Solid pod locations, across Solid pods, or between the local file system and a Solid pod. If the source location is a container or directory, it will recursively copy the container and all sub-containers recursively copying the whole underlying resource tree, including empty containers.

    The default copying behavior ignores .meta, .acl and .acp resources, which can be changed using the --all flag. The copy command automatically copies the full recursive resource tree. At the moment this behavior cannot be altered. In terms of overriding resources, the default setting is that every time a resource is found to already exist, an interactive prompt is shown. This behavior can be altered either by the --never-override or the --override options.

    "},{"location":"documentation/cli/commands/#arguments_2","title":"arguments","text":"

    Arguments:\n  src                   resource or container to be copied\n  dst                   destination to copy file or directory to\n
    The src argument is the location of the resource or container to be moved. If the URL starts with http(s)://, the resource is assumed to be a remote resource, if not the resource is assumed to be local and matched with the local file system. The dst argument is the destination to which the source resource is to be copied. Similarly it uses the http(s):// prefix to decide if the location is local or remote. The default behavior ignores context resources such as .meta, .acl and .acp present in the directories. The --all flag ignores this behavior, though note that for authorization resources, as the target URIs are not edited, copying resources with these authorization resources does not imply they will result in the same access controls as the location they were copied from!

    "},{"location":"documentation/cli/commands/#options_2","title":"options","text":"

    Options:\n  -a, --all             Copy .acl files in recursive directory copies\n  -o, --override        Automatically override existing files\n  -n, --never-override  Automatically override existing files\n  -v, --verbose         Log all read and write operations\n
    The --all option includes .meta, .acl and .acp files in the listing. The --override option automatically overrides existing resources. The --never-override option automatically mitigates resource overrides. The --verbose option shows warnings.

    "},{"location":"documentation/cli/commands/#examples_2","title":"examples","text":"

    Copying a local resource into a Solid pod container. 

    sld cp /path/to/file https://mypod.org/container/\n

    Copying a local resource to a specific remote resource 

    sld cp /path/to/file.ttl https://mypod.org/container/resource.ttl\n

    Copy the contents of container 1 of alice's pod to container 2 of bob's pod.

    sld cp https://mypod.org/alice/container1/. https://mypod.org/bob/container2/\n

    Copy the source container into the target container: https://mypod.org/bob/container2/container1/. 

    sld cp https://mypod.org/alice/container1/ https://mypod.org/bob/container2/\n

    Copy a resource from a solid pod to the local filesystem 

    sld cp https://mypod.org/container/resource.ttl ./resource.ttl\n

    "},{"location":"documentation/cli/commands/#move","title":"Move","text":"

    The mv command moves resources between Solid pod locations, across Solid pods, or between the local file system and a Solid pod. If the source location is a container or directory, it will recursively move the container and all sub-containers recursively copying the whole underlying resource tree, including empty containers. When moving from the local file system, files will not be deleted!

    The default copying behavior ignores .meta, .acl and .acp resources, which can be changed using the --all flag. The move command automatically moves the full recursive resource tree. At the moment this behavior cannot be altered. In terms of overriding resources, the default setting is that every time a resource is found to already exist, an interactive prompt is shown. This behavior can be altered either by the --never-override or the --override options.

    "},{"location":"documentation/cli/commands/#arguments_3","title":"arguments","text":"

    Arguments:\n  src                   resource or container to be moved\n  dst                   destination of the move\n
    The src argument is the location of the resource or container to be moved. If the URL starts with http(s)://, the resource is assumed to be a remote resource, if not the resource is assumed to be local and matched with the local file system. The dst argument is the destination to which the source resource is to be copied. Similarly it uses the http(s):// prefix to decide if the location is local or remote. The default behavior ignores context resources such as .meta, .acl and .acp present in the directories. The --all flag ignores this behavior, though note that for authorization resources, as the target URIs are not edited, copying resources with these authorization resources does not imply they will result in the same access controls as the location they were copied from!

    "},{"location":"documentation/cli/commands/#options_3","title":"options","text":"

    Options:\n  -a, --all             Copy .acl files in recursive directory copies\n  -o, --override        Automatically override existing files\n  -n, --never-override  Automatically override existing files\n  -v, --verbose         Log all read and write operations\n
    The --all option includes .meta, .acl and .acp files in the listing. The --override option automatically overrides existing resources. The --never-override option automatically mitigates resource overrides. The --verbose option shows warnings.

    "},{"location":"documentation/cli/commands/#examples_3","title":"examples","text":"

    Moving a local resource into a Solid pod container. This does not remove the local resource! 

    sld mv /path/to/file https://mypod.org/container/\n

    Moving a local resource to a specific remote resource. This does not remove the local resource! 

    sld mv /path/to/file.ttl https://mypod.org/container/resource.ttl\n

    Move the contents of container1 into container2. This removes container 1.

    sld cp https://mypod.org/alice/container1/. https://mypod.org/bob/container2/\n

    Move the source container into the target container. 

    sld cp https://mypod.org/alice/container1/ https://mypod.org/bob/container2/container1/\n

    Move a resource from a solid pod to the local filesystem 

    sld cp https://mypod.org/container/resource.ttl ./resource.ttl\n

    "},{"location":"documentation/cli/commands/#remove","title":"Remove","text":"

    The rm command can remove resources and/or directories from a remote Solid pod.

    "},{"location":"documentation/cli/commands/#arguments_4","title":"arguments","text":"

    Arguments:\n  urls             URL of container to be listed\n
    The urls parameter accepts a sequence of urls that need to be removed.

    "},{"location":"documentation/cli/commands/#options_4","title":"options","text":"

    Options:\n  -r, --recursive  Recursively removes all files in given container (.acl files are removed on resource removal)\n  -v, --verbose    Log all operations\n
    The --recursive flag must be set when removing container resources. This automatically also removes any contained .acl, .acp and .meta resources. The --verbose flag outputs operation logs.

    "},{"location":"documentation/cli/commands/#examples_4","title":"examples","text":"

    Remove two resources 

    sld rm https://mypod.org/resource1 https://mypod.org/resource2\n

    Remove a container 

    sld rm https://mypod.org/container/\n

    "},{"location":"documentation/cli/commands/#mkdir","title":"Mkdir","text":"

    The mkdir command creates a new container on a remote Solid pod. The command automatically creates all parent directories that do not exist when specifying a subdirectory to create, and fails if the target container already exists.

    "},{"location":"documentation/cli/commands/#arguments_5","title":"arguments","text":"

    Arguments:\n  url            Container to start the search\n
    The url argument is the target container to be created.

    "},{"location":"documentation/cli/commands/#options_5","title":"options","text":"

    Options:\n  -v, --verbose  Log all operations\n
    The --verbose flag outputs operation logs.

    "},{"location":"documentation/cli/commands/#examples_5","title":"examples","text":"

    Create a new container 

    sld mkdir https://mypod.org/container/\n

    "},{"location":"documentation/cli/commands/#touch","title":"Touch","text":"

    The touch command creates an empty resource at the target location. This cannot create containers, for this use the mkdir command. The content type of the created resource is derived from the content type flag or if that is missing from the file extension. If neither can be found an error is thrown.

    "},{"location":"documentation/cli/commands/#arguments_6","title":"arguments","text":"

    Arguments:\n  url                          resource to be created\n
    The url argument is the target resource that is to be created.

    "},{"location":"documentation/cli/commands/#options_6","title":"options","text":"

    Options:\n  -c, --content-type <string>  Content type of the created resource\n  -v, --verbose                Log all operations\n
    the --content-type flag provides The --verbose flag outputs operation logs.

    "},{"location":"documentation/cli/commands/#examples_6","title":"examples","text":"

    Create a new resource 

    sld touch --content-type text/turtle https://mypod.org/container/resource\n

    "},{"location":"documentation/cli/commands/#tree","title":"Tree","text":"

    The tree command provides a tree-structured listing of the target container and all its subcontainers.

    "},{"location":"documentation/cli/commands/#arguments_7","title":"arguments","text":"

    Arguments:\n  url            Base container to construct tree over\n
    The url argument is the target container for which the tree listing is to be made.

    "},{"location":"documentation/cli/commands/#options_7","title":"options","text":"

    Options:\n  -a, --all      Display .acl, .acp and .meta resources\n  -f, --full     Display full resource URIs\n  -v, --verbose  Log all operations\n
    The --all flag includes the .acl, .acp and .meta context resources in the command output. The --full flag displays the resulting resources using their full URIs The --verbose flag outputs operation logs.

    "},{"location":"documentation/cli/commands/#examples_7","title":"examples","text":"

    Create tree listing on the root of a Solid pod. 

    sld tree https://mypod.org/\n

    "},{"location":"documentation/cli/commands/#find","title":"Find","text":"

    The find command can be used to find resources based on their name.

    "},{"location":"documentation/cli/commands/#arguments_8","title":"arguments","text":"

    Arguments:\n  url            Container to start the search\n  filename       Filename to match, processed as RegExp(filename)\n
    The url parameter is the container that forms the root of the resource tree in which the search is executed. The filename parameter is the filename to match, processed as a javascript RegExp.

    "},{"location":"documentation/cli/commands/#options_8","title":"options","text":"

    Options:\n  -a, --all      Match .acl, .acp and .meta files\n  -f, --full     Match full filename.\n  -v, --verbose  Log all operations\n
    The --all flag also matches access control and metadata files. The --full flag matches on and returns the full URIs of resources. The --verbose flag outputs operation logs.

    "},{"location":"documentation/cli/commands/#examples_8","title":"examples","text":"

    Find a resource named card in the profile/ container. 

    sld find http://mypod.org/profile/ card\n

    "},{"location":"documentation/cli/commands/#query","title":"Query","text":"

    The query command executes a SPARQL query over a target resource or container. In case a container is queried, all contained resources and subcontainers are recursively queried as well. The query itself is not federated, each query is individually evaluated over every resource. The following resources are included when querying: .ttl, .trig .nt, .nq, .jsonld, .rdf both on their resource extensions and their content type.. The Comunica engine is used for query evaluation. Note that only SELECT queries are supported!

    "},{"location":"documentation/cli/commands/#arguments_9","title":"arguments","text":"

    Arguments:\n  url              Resource to query. In case of container recursively queries all contained files.\n  query            SPARQL query string | file path containing SPARQL query when -q flag is active\n
    The url argument is the target resource or container to query. Containers are queried recursively on all contained resources in its resource tree. The query argument is either a SPARQL query in quotes, or the path to a file containing a sparql query if the --queryfile flag has been set.

    "},{"location":"documentation/cli/commands/#options_9","title":"options","text":"

    Options:\n  -a, --all        Match .acl and .meta files\n  -q, --queryfile  Process query parameter as file path of SPARQL query\n  -p, --pretty     Pretty format\n  -f, --full       Return containing files using full filename.\n  -v, --verbose    Log all operations\n
    The --all flag includes .acl, .acp and .meta resources in the query targets. The --queryfile flag changes the query argument to a file path for a resource containing a SPARQL query. The --pretty flag outputs the results in a table. The --full flag gives the full resource URIs of where the matches were found. The --verbose outputs operation logs.

    "},{"location":"documentation/cli/commands/#examples_9","title":"examples","text":"

    Evaluating a federated query over all resources in the profile container to look for entites with a given name. 

    sld query https://mypod.org/profile/ \"select ?entity ?name where { ?entity foaf:name ?name }\" --federated \n

    Evaluating a query stored in a local resource over the resources in the profile container individually, including .acl, .acp and .meta resources. 

    sld query --queryfile https://mypod.org/profile/ /path/to/sparql_query_file --all\n

    "},{"location":"documentation/cli/commands/#edit","title":"Edit","text":"

    The edit command enables the editing of remote resources using a local editor. The command will remain in standby until changes are saved, after which pressing a button in the shell will upload the resource to the Solid pod.

    Note: there currently is still a bug for longer edits, where saving the changes when a client session has expired will not be able to save the resource back to the pod. This should not be a problem when using client credentials.

    "},{"location":"documentation/cli/commands/#arguments_10","title":"arguments","text":"

    Arguments:\n  url                                       Resource URL\n
    The url argument is target resource that will be edited.

    "},{"location":"documentation/cli/commands/#options_10","title":"options","text":"

    Options:\n  -e, --editor <path_to_editor_executable>  Use custom editor\n  -t, --touch                               Create file if not exists\n  -v, --verbose                             Log all operations\n
    The --editor option enables the use of a specific local editor to modify the resource. The --touch option will create the resource if it does not exist yet. The --verbose option outputs operation logs.

    "},{"location":"documentation/cli/commands/#examples_10","title":"examples","text":"

    Editing a resource using the default editor. 

    sld edit https://mypod.org/resource1\n

    Creating and editing a resource using vs-code (code) 

    sld edit --touch --editor code  https://mypod.org/non_existing_resource\n

    "},{"location":"documentation/cli/commands/#access","title":"Access","text":"

    The access command is used to manage resource access. This is explained in the access management section.

    "},{"location":"documentation/cli/commands/#auth","title":"Auth","text":"

    The auth command is used to manage authentication in Bashlib. This is explained in the authentication management section.

    "},{"location":"documentation/typescript/css-specific/","title":"css specific typescript","text":""},{"location":"documentation/typescript/example-requests/","title":"Example requests ts","text":""},{"location":"documentation/typescript/metadata/","title":"Handling metadata","text":""},{"location":"documentation/typescript/overview/","title":"Overview Usage for Typescript","text":""}]} \ No newline at end of file diff --git a/documentation/site/sitemap.xml b/documentation/site/sitemap.xml index 9401346..92d172f 100644 --- a/documentation/site/sitemap.xml +++ b/documentation/site/sitemap.xml @@ -2,58 +2,54 @@ https://SolidLabResearch.github.io/Bashlib/ - 2025-01-07 + 2025-01-08 https://SolidLabResearch.github.io/Bashlib/tutorial/ - 2025-01-07 + 2025-01-08 https://SolidLabResearch.github.io/Bashlib/contributing/making-changes/ - 2025-01-07 + 2025-01-08 https://SolidLabResearch.github.io/Bashlib/documentation/overview/ - 2025-01-07 + 2025-01-08 https://SolidLabResearch.github.io/Bashlib/documentation/cli/access/ - 2025-01-07 + 2025-01-08 https://SolidLabResearch.github.io/Bashlib/documentation/cli/aliases/ - 2025-01-07 + 2025-01-08 https://SolidLabResearch.github.io/Bashlib/documentation/cli/authentication/ - 2025-01-07 + 2025-01-08 https://SolidLabResearch.github.io/Bashlib/documentation/cli/commands/ - 2025-01-07 - - - https://SolidLabResearch.github.io/Bashlib/documentation/cli/overview/ - 2025-01-07 + 2025-01-08 https://SolidLabResearch.github.io/Bashlib/documentation/typescript/authentication/ - 2025-01-07 + 2025-01-08 https://SolidLabResearch.github.io/Bashlib/documentation/typescript/css-specific/ - 2025-01-07 + 2025-01-08 https://SolidLabResearch.github.io/Bashlib/documentation/typescript/example-requests/ - 2025-01-07 + 2025-01-08 https://SolidLabResearch.github.io/Bashlib/documentation/typescript/metadata/ - 2025-01-07 + 2025-01-08 https://SolidLabResearch.github.io/Bashlib/documentation/typescript/overview/ - 2025-01-07 + 2025-01-08 \ No newline at end of file diff --git a/documentation/site/sitemap.xml.gz b/documentation/site/sitemap.xml.gz index a1545a3f4521a1e9e085ac488973b99fc8ea0d6f..5992b9171789934b57a7adedc930e1e359aa7c6e 100644 GIT binary patch literal 331 zcmV-R0kr-fiwFn+zwU4$z@f zryd_b(`-ysvRsjl)4#8Bpvayf;zEhw@jwz%y*)Ua?I{TRVUsV*D$i&@-|?{9urq>vyok9NO;tYT%_56(OmIG(q_!TL zV-|^N-o54S71}ovf`EOwW9_H5WN)59ddsb;%`xCQ9z>n*npL%WD5_;qt)t7ub}nfC zE8bXJC-s5B-W3A7)HD4ZNiguJ>9+2Q5k(3a3HggLO+q?=8!Z)qekKx4 dbk>d(I#5WH?)GQ+q~eF)`~kWT8ZICR004f~pn?DZ literal 334 zcmV-U0kQrciwFpSZhU6~|8r?{Wo=<_E_iKh0L_-UZo@DPhW9*$;oX)Kpy+|b0XlT* z)Z+nYnzf1Qa7{W+-@eL$B72623#A_v`9Y)rt+#t;vmK4X!Ef?qS>+jd3@!U^lYf4^ z6c72fUaY6l3TYODy=?Mcb$Bvnp660n$-y9H7&{}_$Bme?XsYrtuNPUgLxR)lXlom= zK4g)Y<~>+$U!i#;AsDeQJJx<`N)F~3q_^CdwK*KPJP)ESwDqc5-4)fcsP1FPSvwUp z{}r#St&@h4!QK=CgV&LpNn>A(gYW1H?7?>=H|1&rPL8~S#`!TJ4$_WkP6!Dt8$cwH z)SxVbP;yk0_EBIwNom1ha1MN%+MOjh_4+%I;K+lf+tCX~6e(mN - + Skip to content @@ -438,15 +438,6 @@
      -
    • - - - Index - - - -
      • -
    • @@ -454,49 +445,13 @@ -
      • - -
    • - - - Setting up Bashlib - - - -
      • - -
    • - - - Bashlib-css - - - -