SOLID_AUTH(1p)

hey bestie 💖 welcome to the manual page for solid_auth — that's section 1p of the User Contributed Perl Documentation, page title SOLID_AUTH(1p). It's your whole toolkit for living your pod life: authenticating, curling, mirroring, cleaning, the works. Let's get into it ✨

---

✨ NAME ✨

solid_auth — a Solid management tool. That's it, that's the vibe 💅

---

🎀 SYNOPSIS 🎀

okay so here's the whole vibe in one blob, look at her go:

# Set your default webid
export SOLID_WEBID=https://timbl.inrupt.net/profile/card#me

# Authentication to a pod
solid_auth authenticate

# Get the http headers for a authenticated request
solid_auth headers GET https://timbl.inrupt.net/inbox/

# Act like a curl command and fetch authenticated content
solid_auth curl -- -X GET https://timbl.inrupt.net/inbox/

# Add some data
solid_auth curl -- -X POST \
      -H "Content-Type: text/plain" \
      -d "abc" \
      https://timbl.inrupt.net/public/

# Add a file
solid_auth curl -- -X PUT \
      -H "Content-Type: application/ld+json" \
      -d "@myfile.jsonld" \
      https://timbl.inrupt.net/public/myfile.jsonld

# Set a solid base url
export SOLID_REMOTE_BASE=https://timbl.inrupt.net

# List all resources on some Pod path
solid_auth list /public/

# Get some data
solid_auth get /inbox/

# Post some data
solid_auth post /inbox/ myfile.jsonld

# Put some data
solid_auth -f put /public/myfile.txt myfile.txt

# Patch data
solid_auth -f patch /public/myfile.txt.meta  - <<EOF
INSERT DATA { <> <http://example.org> 1234 }
EOF

# Create a folder
solid_auth -f put /public/mytestfolder/

# Delete some data
solid_auth delete /public/myfile.txt

# Mirror a resource, container or tree
mkdir /data/my_copy
solid_auth -r mirror /public/ /data/my_copy

# Upload a directory to the pod
#  Add the -x option to do it for real (only a test without this option)
solid_auth -r upload /data/my_copy /public/

# Clean all files in a container
#  Add the -x option to do it for real (only a test without this option)
solid_auth --keep clean /demo/

# Clean a complete container
#  Add the -x option to do it for real (only a test without this option)
solid_auth -r clean /demo/

---

🌸 ENVIRONMENT 🌸

the env vars bestie, these are the settings your shell can whisper into solid_auth:

• SOLID_WEBID — your WebId. yes queen, the whole identity.
• SOLID_REMOTE_BASE — the Base URL that gets used for all delete, get, head, options post, put, patch requests. one base to rule them all 💫
• SOLID_CLIENT_ID — the URL to a static client configuration. peek at etc/web-solid-auth.jsonld for an example. that file, edited for your own environment, needs to be published on some public accessible webserver. no cap 📢

---

🦋 CONFIGURATION 🦋

same energy as the env vars but as flags you can just ~say out loud~ on the command line:

• --webid — your WebId.
• --base — the Base URL that is used for all delete, get, head, options post, put, patch requests.
• --clientid — the URL to a static client configuration. see etc/web-solid-auth.jsonld for an example. this file, edited for your own environment, needs to be published on some public accessible webserver.
• --skip — skip resources that already exist (mirror).
• --delete — delete local files that are not in the remote container (mirror).
• --keep — keep containers when cleaning data (clean).
• --etag=STRING — only update the data when the 'Etag' header matches the given string (put,patch). e.g. use the head command to find the ETag of a resource:

$ solid_auth head /demo/LICENSE
...
ETag: "189aa19989dc47eab46c9f2e8c47d0836bb08cb09f7863cbf3cd3bb9a751be27"
...

now update the resource with ETag protection ✨

$ solid_auth \
    --etag=189aa19989dc47eab46c9f2e8c47d0836bb08cb09f7863cbf3cd3bb9a751be27 \
    put /demo/LICENSE LICENSE

• --force | -f — force overwriting existing resources (put, patch). careful bestie, she WILL clobber.
• -r — recursive (clean, mirror, upload).
• -x — do it for real. the commands clean and upload will run by default in safe mode. no -x means no commits to the timeline, just vibes and a test run.
• -H name=value — add a header to a request (repeatable) for get, post, head, options and delete. stack them like friendship bracelets 🫶

---

👑 COMMAND 👑

here's the whole squad, one by one:

• authenticate — start an authentication process for your WebId. you'll be presented with a URL that you need to open in a webbrowser. after a successfull login the command can be closed.

the webbrowser needs to be opened on the same host as the where you where you run the solid_auth command.

• headers METHOD URL — return the Authentication and DPoP headers for a HTTP METHOD request to URL.
• curl CURL-OPTS — execute a curl command with Authentication and DPoP headers added. add a -- option to the CURL-OPTS to stop solid_auth from interpreting Curl options.
• list URL — list the resources in a LDP container at URL.
• mirror [-rx] [--skip] [--delete] URL DIRECTORY — mirror the contents of a container to a local directory. optional provide -r option for recursive mirror.
• upload [-rx] DIRECTORY URL — upload a directorty to a container. optional provide -r option for recursive upload. with the -x option, the command will run in demo mode.
• clean [-rx] [--keep] URL — clean all resources in a directory. optional provide -r option for recursive clean. with the -x option, the command will run in demo mode. with the --keep options all container will be kept.
• get URL — return the response of a HTTP GET request to URL.
• post URL FILE [MIMETYPE] — return the HTTP Message of a HTTP POST request of the FILE with MIMETYPE. uses libmagic to guess the mimetype.
• put URL [FILE] [MIMETYPE] — return the HTTP Message of a HTTP PUT request of the FILE with MIMETYPE. uses libmagic to guess the mimetype.

when the URL ends with a slash (/), then a new container will be created. 🪄

• patch URL FILE|SPARQL — send the contents of a SPARQL patch file or string to a URL. return the HTTP Message of the HTTP PATCH request to the URL.
• head URL — return the HTTP Header of a HTTP HEAD request to URL.
• head OPTIONS — return the HTTP Header of a HTTP OPTIONS request to URL.
• delete URL — return the HTTP Message of a HTTP DELETE request to URL.
• id_token — show the contents of the JWT id token.
• access_token — show the contents of the JWT access token.

---

🌈 INSPIRATION 🌈

this was very much inspired by the Python solid-flask code by Rai (http://agentydragon.com) at (https://gitlab.com/agentydragon/solid-flask), and Jeff Zucker's (https://github.com/jeff-zucker) Solid-Shell at (https://www.npmjs.com/package/solid-shell). giving credit where credit is due, iconic behaviour fr fr 🫡

---

💜 COPYRIGHT AND LICENSE 💜

this software is copyright (c) 2021 by Patrick Hochstenbach.

this is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself. free as in freedom, periodt.

---

and that's the whole page bestie 💖 this was perl v5.36.0, dated 2023-09-04, and the page is SOLID_AUTH(1p). go forth and pod, you main character 🎀🦋⭐