You can learn more about this git repository by cloning it like this:
git clone https://supertxt.net/git/urltocmd--hash=2739b8a --date=2025-03-24T13:53:50-04:00 "Minor readme fix"
--hash=ded0294 --date=2025-03-24T13:07:49-04:00 "Update the readme with more examples of headers, prompting, and print-curl"
--hash=7c87e75 --date=2025-03-24T11:50:42-04:00 "Add a new --install option for urltocmd"
--hash=8af13d4 --date=2025-03-24T07:35:54-04:00 "Make http-method case insensitive"
--hash=47fe164 --date=2025-03-22T19:09:39-04:00 "Pretty print and augment JSON outputs with ssc commands alongside URLs"
--hash=e4b1d2a --date=2025-03-22T10:33:57-04:00 "Fix the list of available commands in online help and README"
--hash=6a1c270 --date=2025-03-22T10:30:04-04:00 "Fix arg slice when using --ssc-action option"
--hash=7994f6e --date=2025-03-22T10:25:34-04:00 "Separate cat from srch subcommands based on -q= query parameter"
--hash=f0a6960 --date=2025-03-22T08:23:32-04:00 "Update the README removing the --q= option in favour of a plain search text argument"
--hash=7a0c121 --date=2025-03-22T08:21:16-04:00 "Make text search ?q=abcde into extra argument instead of an option for better long string handling"--id=main --hash=2739b8a --date=2025-03-24T13:53:50-04:00
Convert a URL into a command that is suitable for running on a command-line.
urltocmd https://somewebsite.org/foo%20bar/baz
--
somewebsite.org \
cat \
"foo bar/baz"
Doesn't the command look easier to understand than the original URL?
The command-line can be compressed into a single line using the `--single-line` flag for easier copy and pasting.
urltocmd https://wikipedia.org/wiki/Carlisle --single-line -- wikipedia.org cat wiki/Carlisle
Another strength of command-lines is this ability to either span multiple lines or compress into one. They've become very flexible.
This tool exists to increase awareness of the pitfalls of URLs and highlight how CLI can be a nicer, and more ergonomic interface.
URLs are difficult to read:
URLs require special tools to interpret, such as web browsers and `curl` bypassing natural OS mechanisms. Besides, why are 99% of them repeating the "http(s)://" over and over?
So, why not use commands instead? They are a much more natural interface, and are certainly more readable. They interact well with the operating system. You can ask them for help using `--help`, or even a Unix manual page.
One of the goals is to help and increase the number of site-specific command-line interfaces that can be run directly at the shell. Instead of using curl to interact with your favorite website, you can have a site-specific command that works with the typical paths, query parameters of it instead. If it becomes sophisticated enough, it can be shared with the world, and perhaps the website might make an official one someday.
Meanwhile, there is a special site-specific command line tool that can help you today.
The ssc command is a little like curl, but without the URL and has one less letter to type each time. For example, this will do an HTTP GET on a specific resource of a fictional RESTful site example.com:
ssc example.com cat pets.json -- ["Polly the parrot", "Dolly the sheep", "Ginger the duck"]
This is much like how you could read the contents of a file on another computer using ssh. The command is nearly identical, just with "ssc" in place of "ssh".
And now let's look at a particular pet. Spaces are fine, we just put quotes around them.
ssc example.com cat "pets/Polly the parrot.json"
--
{
"name": "Polly the parrot",
"city": "London"
}
Or get, modify and put an update to the city to Carlisle:
ssc example.com cat "pets/Polly the parrot.json" | jq '.city="Carlisle"' | ssc example.com cat -Xput -d@-.json "pets/Polly the parrot.json"
We can also pass site parameters to places where typically you would use URL query parameters. Let's list all of the pets in Carlisle:
ssc example.com cat pets.json --city=Carlisle -- ["Polly the parrot", "Ginger the duck"]
Underneath, the ssc tool is creating a URL for these requests. We can ask it for the URL using the `print-url` command:
ssc example.com pets.json --city=Carlisle -A=print-url -- https://example.com/pets?city=Carlisle
Note that in more complex scenarios like PUT requests ssc is creating a full HTTP request with the HTTP method, request body, and redirecting the output to from standard input. In those cases there's more than just a simple URL involved, it's more like a complex curl command, so the print URL function might produce an error. You can print an entire curl command using "print-curl".
echo "[]" | ssc example.com -Xput -d@-.json pets.json --city=Carlisle -H "Authorization: Bearer ABCDE" -A=print-curl -- curl -H "Authorization: Bearer ABCDE" -d- https://example.com/pets
REST API's can become really intricate, usually much more than the simple example above. We would like to use OpenAPI as a way to identify higher-level commands instead of paths. This can increase the ergonomics (ie. less typing involved) of the site specific commands. Also, the OpenAPI specification can help users to see the capabilities of a site. Let's try inspecting a website using its OpenAPI specification published online, but more like how we would ask a command-line tool for its help:
ssc shopping.example.com --openapi=https://shopping.example.com/api/spec.yaml --help
--
Usage: shopping.example.com
[command]
The following commands are available:
* cat - display result of an HTTP API
* srch - search using a full text query
* showShoppingCartContents
* addItemToCart
* searchForWidgets
You can repeat the above command with your up-arrow (in most modern shells), remove the "--help" flag and replace it with any of the commands to access the functionality. But, we are still having to remember to type the "ssc" command, and providing that long URL to the spec. Let's make things a little easier for ourselves by installing the shoping site as a command on our system that remembers the OpenAPI specification. We can do this by using the `urltocmd --install` option.
urltocmd --install --openapi=https://shopping.example.com/api/spec.yaml https://shopping.example.com
Often API's require a special authorization header. We can ask `urltocmd` to prompt us for the header's value, which saves it to a file protected using filesystem permissions and we don't need to provide it again. The special value '-' in the value of the Authorization header below performs the protected transfer of the information:
urltocmd --install -H 'Authorization: -' https://shopping.example.com Enter header Authorization value: Bearer ABCDE
Now, if you add the `~/.ssc/bin` directory to your PATH you get the site-specific command wrapper with the OpenAPI specification and the authorization header. You can now run the commands just like regular commands on your system.
shopping.example.com showShoppingCartContents --user=me
Or, even get more detailed help for the command in the expected way:
shopping.example.com showShoppingCartContents --help
--
Usage: showShoppingCartContents
--user=<userId>
[--limit=10]
[--foo=<bar>]