With the growing number of people interested in trying out the community testnets and official playgrounds, and with @ChrisO having made installation easier for Windows users with his PowerShell script, we thought it would be a good time to go over the basic commands so folks can get their hands dirty and join in when next a comnet or testnet is up and running.
Chris has made some more updates to the CLI user guide over the last few days, including:
- Moving the XorUrl section nearer to the top of the document, where it makes more sense
- Rewriting the NRS,
dogdocumentation to make it a bit leaner
- Adding a new section on Keys, where it’s relevant to current network functionality.
Next step will be to reintroduce shell completions (so you’ll be able to complete a command by hitting Tab again - not massively useful for
dog but a real time-saver with longer commands).
Elsewhere, @yogesh has completed the pull flow (where adults automatically retrieve the data they should be holding from the network) and is putting it through its paces with testing, and @davidrusu has got membership issues with BLS keys sorted and is currently working on advancing the integration work there.
And we’re pleased to welcome @oetyng back from his sabbatical.
He jumped in on the connection deadlock issue, and with a refactor of the connection handling that got merged today, tests are now looking much more stable. Some work in that area continues as it relates to the refactored membership (pending PR) and improvements in messaging that the team is discussing now.
The Command Line Interface can look a bit scary to begin with, like a step back to the 1990s, but for the community testnets and playgrounds it’s mostly just a matter of copying and pasting commands into a terminal such as PowerShell on Windows or Terminal on Mac/Linux and hitting Enter.
Here are some of the main commands you’ll need to participate. Note: best to wait until there’s a live testnet/playground before trying them.
When a new community testnet or playground is announced there are some basic instructions on getting started, and you’ll normally see something like this (Mac/Linux)
curl -so- https://raw.githubusercontent.com/maidsafe/safe_network/main/resources/scripts/install.sh | bash
or this (Windows PowerShell)
Set-ExecutionPolicy Bypass -Scope Process -Force; iex ((New-Object System.Net.WebClient).DownloadString('https://raw.githubusercontent.com/maidsafe/safe_network/main/resources/scripts/install.ps1'))
Pasting this into your terminal and hitting enter should download and install
safe, including updating PATH, which is a list of locations where the operating system will look for installed applications.
For more instructions, please see the updated Quick Start section of the CLI user guide.
The next commands download the configuration file for a test network (in this case called ‘comnet’) and let you connect to it. They will look something like this (Note: these commands won’t work just now as no comnet / testnet is currently live):
safe networks add comnet https://sn-comnet.s3.eu-west-2.amazonaws.com/node_connection_info.config
safe networks switch comnet
You should now be able to upload and download data.
If you want to try your luck at joining the test network as a storage node the command below will download and install the node software.
safe node install
You can then follow the test net instructions to join.
More info: Provide a node
All content uploaded to the network has an address, a URL. The Safe Network uses an address that’s created from the content itself called a XorUrl, which looks like this:
The XorUrl contains information about where the data is located, what type of data it is (e.g. image, video, text) and so on. XorUrl’s can be converted into human-readable addresses using Safe Network’s Name Resolution System (NRS).
More info: XorUrl
To upload data you use this command :
safe files put
So if your file
my-pic.jpg is in your current directory (as shown by the terminal prompt, e.g. C:\Users\Me\Pictures) then this will upload it to the network:
safe files put my-pic.jpg
If successful you’ll see the XorUrl of your uploaded file, e.g.
To upload a folder called ‘to-upload’ that contains some files (e.g. C:\Users\Me\Pictures\to-upload), the command would be
safe files put ./to-upload/ --recursive
If this is successful you’ll see XorUrl’s for the folder and each file it contains.
To list the files in a container with XorUrl
safe://hyryyryyndnbzqc9zmuu6iggm7j5obyx3sj8idcpg7ds9jdiwtjs1gjipd3ioeuy use the
ls (list) command:
safe files ls safe://hyryyryyndnbzqc9zmuu6iggm7j5obyx3sj8idcpg7ds9jdiwtjs1gjipd3ioeuy
More info: Put
If we know its XorUrl we can ‘sniff out’ what type of data it is using dog . If we
dog the my-pic image we uploaded before using its XorUrl we can see it’s a jpeg:
safe dog safe://hy8oycyybrqkkwrnmneshqetpnzfoncfw9qznm331515xk936hm1gsrkkw1cy
media type: image/jpg
More info: Dog
The simplest way to download a file is by using
cat . To download our file
safe://hy8oycyybrqkkwrnmneshqetpnzfoncfw9qznm331515xk936hm1gsrkkw1cy to our current directory we need to give the downloaded file a name (otherwise it will just output a load of nonsense on the screen), so if we know it’s a jpg:
safe cat safe://hy8oycyybrqkkwrnmneshqetpnzfoncfw9qznm331515xk936hm1gsrkkw1cy > my-new-filename.jpg
More info: Cat
That should be enough to get started. Hope to see you on the next community testnet or playground.
Feel free to reply below with links to translations of this dev update and moderators will add them here:
As an open source project, we’re always looking for feedback, comments and community contributions - so don’t be shy, join in and let’s create the Safe Network together!