en-US/about_PSGemini.help.txt
|
TOPIC
about_psgemini SHORT DESCRIPTION Get resources by using the Gemini protocol. LONG DESCRIPTION PSGemini is a PowerShell module designed to access, view, download, and interact with resources available over the Gemini protocol. Designed to be "somewhere between Gopher and HTTP", Gemini is growing in popularity. It's time it had a PowerShell module. This module has some cmdlets, but the important one is Invoke-GeminiRequest. Modeled after `Invoke-WebRequest`, it can be used similarly. The syntax and output are similar. Certificate Trust The Gemini protocol uses certificates in a trust on first use (TOFU) model. To keep track of this, PSGemini saves found certificates to a file. That file is saved at $env:PSGeminiTOFUPath. If that is not defined, it defaults to `${env:HOME}/.PSGemini_known_hosts.csv`. While strongly discouraged, if you've managed to find my conceptual help, you might be the type who wants to mess with the trust store. You can do so by using one of these cmdlets: - Get-PSGeminiKnownCertificate - Add-PSGeminiKnownCertificate - Remove-PSGeminiKnownCertificate Even more strongly discouraged: you may open the CSV file in a text editor, Excel, LibreOffice Calc, or another app. Aliases (or, Why Not `igr`?) You can use the aliases Invoke-GemRequest or igemr. (Why not `igr`? That is already used by my other module, PSGopher. Fans of the small web might have both installed.) Client Certificates Client certificates are supported. Specify the -Certificate parameter to use one. FavIcons Why not have a little fun? Someone made a draft RFC to bring something like favicons to Gemini. In the spirit of the protocol, we won't make any extra requests, so this is disabled by default. To request a resource's favicon, use the `-FavIcon` parameter for `Invoke-GeminiRequest`. TLS 1.3 Support This cmdlet does support TLS 1.3, but relies on the host to support it, too. There may be issues using it with PowerShell 7 on some platforms. hus, the `Invoke-GeminiRequest` cmdlet will make a best effort to use TLS 1.3 before falling back to TLS 1.2. Per the specification's intent, no older protocols may or will be tried. EXAMPLES EXAMPLE 1: ACCESS RESOURCES PS C:\> Invoke-GeminiRequest gemini://gemini.circumlunar.space StatusCode : 20 StatusDescription : text/gemini Content : # Project Gemini ## Overview Gemini is a new internet protocol which: * Is heavier than gopher * Is lighter than the web * Will not replace either * Strives for maximum power to weight ratio * Takes user privacy very seriously […] Connects to the Gemini server at gemini.circumlunar.space and returns the result. EXAMPLE 2: DOWNLOAD RESOURCES PS /Users/colin> Invoke-GeminiRequest gemini://colincogle.name/pgp.txt -OutFile pgp.txt PS /Users/colin> Get-Item pgp.txt Directory: /Users/colin UnixMode User Group LastWriteTime Size Name -------- ---- ----- ------------- ---- ---- -rw-r--r-- colin wheel 2/8/2022 08:05 5218 pgp.txt You can use the `-OutFile` switch to download files from Gemspace. NOTE The Gemini specification uses a TOFU model for remembering certificates. To keep track of this, PSGemini saves found certificates to a file. That file is saved at $env:PSGeminiTOFUPath. If that is not defined by the user, it defaults to `${env:HOME}/.PSGemini_known_hosts.csv`. TROUBLESHOOTING NOTE Client certificates have not been fully tested. If you encounter any issues, come complain on GitHub. The link follows. SEE ALSO Issues? Rants? Raves? Find this module on GitHub: => https://github.com/rhymeswithmogul/PSGemini If you'd like to know more about Gemini, check out its unofficial official site at either: => gemini://gemini.circumlunar.space, or => https://gemini.circumlunar.space The Gemini protocol specification is here: => gemini://gemini.circumlunar.space/docs/specification.gmi If you like Web/WWW/HTTP alternatives, why not check out my other module: => PSGopher: https://github.com/rhymeswithmogul/PSGopher KEYWORDS Gemini, Gemlog, Gemblog, Geminispace, Gemtext, SSL, TLS, PowerShell Core, the small web |