Update 24 February, 2022

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.

General progress

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, cat and dog documentation 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 cat and dog :slightly_smiling_face: 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.

Using the CLI

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.

Downloading and installing the safe application

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.

Connecting to a test network

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.

Joining as a node (optional)

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

Uploading a file or folder

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. safe://hy8oycyybrqkkwrnmneshqetpnzfoncfw9qznm331515xk936hm1gsrkkw1cy

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

Finding info about stored data

If we know its XorUrl we can ‘sniff out’ what type of data it is using dog :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

Output includes: media type: image/jpg

More info: Dog

Downloading a file

The simplest way to download a file is by using cat :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. :playground_slide:

Useful Links

Feel free to reply below with links to translations of this dev update and moderators will add them here:

:russia: Russian ; :germany: German ; :spain: Spanish ; :france: French; :bulgaria: Bulgarian

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!


First. :tada:

CLI and vdash

For anyone who wishes to use vdash to monitor their node from the terminal, remember the following extra points about the CLI:


  • nodes must be started with: RUST_LOG=safe_network=trace safe node join #etc
  • same when starting a local test network
  • logfiles must be in default format (text not JSON)

More on vdash here:


Second time a charm :slight_smile:


Third for the first time


Thanks so much to the entire Maidsafe team for all of your hard work! :racehorse:


Are there any extensions to the node join command that would help you with this?


I’m not sure what you mean. The only thing I need here is to ensure the log level is trace rather than the default (info).


It was just in case anything could be done to make the integration easier.


There is so much happening with DBC on github too, feels like it will be jumping on us soon!


Thanks @chriso. The main thing will probably be adding or tweaking the log messages to give access too useful metrics, but best to wait until the code settles down.


Why cat and not safe files get? I think for people not familiar with Linux (or CLI in general) using GET is coherent with PUT and easier to understand than doing CAT and sending its output to file.


You can only get files if you also have the container address, so it’s more complex for beginners. That’s why the testnet examples always use cat and redirect to a file


I have personally 2 small remarks when analyzing log files with Telegraf Tail:

  • read_bytes in “Node resource usage:” is always 0

  • I didn’t find a proper way to get current node prefix:

    • “Known prefix after update:” is generated in a loop which means several of them can be listed
    • “Section updated: prefix:” is reserved for elders and unavailable for adults
    • prefix at the end of “Node resource usage:” isn’t in the right format (000000… instead of ())

Please note that I generated sn_node a few days ago and so my remarks may not be relevant anymore.


Thx @maidsafe team & all…


Looks like some solid updates - Thanks MaidSafe Team! The finish line may not be in sight, but in the race of the turtle and the hare, the turtle is winning. First over the line with a product doesn’t matter if nobody will want to use that product in 10 years as it’s been made beyond obsolete by a far superior product.


Not trying to distract from all the good things going on, but wouldn’t “Name Resolution Service” be a more appropriate description? Precise language is important here imo.


I have issued a small PR to change this behavior (one line modification!).

I am not sure this is the best way to get the prefix for the dashboard, but anyway the prefix should be displayed using its usual binary representation and not its name.

1 Like

It’s distinct from a Service, so System seems appropriate to me. Why do you see it as more service than system?

To me a service implies an entity providing something, a server, organisation, business etc. whereas a system is just code, and I think that’s nearer to the truth.


If you look up the traditional dictionary definition of each word, then “service” is more fitting from the client perspective. Even more so from the perspective of safe acting as a world computer. It’s a service for the client end user that translates xor into human language and vice versa. The safe network itself is a system.

1 Like