SAFE CLI - High Level Design Document

Spoiler - once the api changes have been implemented (and @dask and me have a little bit of time again) our goal would be to ship pySafe with a simple command line tool too and a little local rest/graphQl server where random languages can just use ‘local Web calls’ to interact with an alternative authenticator… Once we have implemented the basic ffi functions and some comfort functions to pySafe that take care of the annoying handle stuff this should be very straightforward, not a problem at all to make and easy to understand even if you are no python Pro… (not claiming I’d be)

… As of now the largest hurdle simply is that both of us are super busy and don’t manage to have the hours to do it…
If someone wants to help out feel free to join us and just improve pySafe +open a pr :blush:

(why it needs to be rust was something I was wondering too because I assume that all of the functionality should be way harder to create and for sure is less easy to read - but then again I thought maybe it’s just me and since they seem to have already something running they seem to be faster with it than I would have expected ; )


All lower layers are in Rust, implementing it in Rust is the most straight forward while at the same time we can then have a FFI to expose it for other langs. Adjusting the FFI to expose this APIs you then leave Rust devs/apps out of it. As per being all part of SCL, it could be, but if we get the most commons abstractions in this crate you shouldn’t need any of the current SLC API, only if you are trying to read/write data not following these conventions/specs is that you’d additionally need those other APIs to be also included in your app.


Yes, I agree about a potential API being in Rust. What I question is the rationale behind implementing the CLI in Rust. (Personally I don’t mind, but I think the answer might help understand the architecture and goals.)

Perhaps I am wrongfully making a distinction between the API and CLI? Are these implied to be in the same single Rust crate? (Whereby the CLI closely mirrors the API calls so that the CLI is merely passing the command line arguments into the API functions?)


It is just easier for us and will allow a static binary as well. It could be in any language really, but rust is a good candidate here.


This is where we want to be, CLI cmds is just the UI, it has an API which maps hopefully 1-to-1 with what cmds exposed, then that internal API becomes published and can be used by other Rust apps, FFI very thin layer. E.g. if we have $ safe wallet transfer ... and safe wallet balance ... the API can hopefully be wallet_transfer(...) and wallet_balance(...), and so on for all cmds and sub-cmds


I don’t want to make another account on the dev side to reply there. But I really like @bzee’s point. i.e., “All the acronyms in the poll sound very generic. Why not just extend what is already known — prefix DNS with SAFE: SDNS.”

It would make it easy for new entrants to quickly understand what it is. I was going to say dDNS, with d for decentralized, but that too would be generic. I like SDNS.


Something with low priority (maybe for other people to do later), but that is what I think of: for Linux one could reduce the characters to type if e.g. it could be made that symlink ‘scat’ to the ‘safe’ cmdline tool is translated the ‘safe cat’ by the safe cmdline tool.
You could get the same effect with a bash alias however.
From example from

mkdir bbdir
for i in $(busybox --list)
ln -s busybox bbdir/$i


I think when doing operations on the CLI that need safecoins, there should be some sort of prompt for asking the user like This operation will approx. cost 3 safecoins. Continue?.
I imagine a scenario where a user might accidentally upload a huge amount of big files and has to pay for it.

Caveats and potential solutions

  • Is it possible to know the cost of safecoins before the operation takes place? I really don’t know.
  • Headless mode
    • we must be able to deactivate it when in headless mode
    • maybe we can also have a config where you can set an upper limit of safecoins to spend per operation
  • Sync mode
    • in sync mode it might be better to set an upper limit of safecoins to spend per time period (e.g. max 3 safecoins per week)
    • here the problem is that we might have already spend 3 safecoins during 6 days. Now what should happen?
      • should the sync just exit?
      • should the sync stop and continue after the 7th day (after the next time period begins)
      • maybe we should think about a moving average instead?

Overall, I think, this mechanism is really important, because we are dealing with real money here in the end.

General question that ties in to the above points: Is there a way to undo an operation and get the safecoins back that have been spend on that operation? That might make the above points obsolete. :wink: See also:

Thanks for the interesting write-up of the SAFE CLI. I am really looking forward to see it in action in the wild! :smile_cat:


Hey @janriemer, thanks a lot for this input/feedback/thoughts.

I think the --dry-run arg should be the answer to what you suggest, which eventually should show you the potential cost of it, if it is effectively possible to estimate the cost.

Some other thoughts were that the interactive shell we envisioned to have, can perhaps be the place where it prompts you for many things including the potential cost perhaps, so you could then jump into the interactive shell with just running safe, and then inside of it you are prompted for several things and defaults are inverted, so e.g. in interactive shell you do:

$ safe
Welcome to SAFE CLI interactive shell!
Type "help" for more information about supported commands.
Type "exit" to exit this shell. Enjoy it!

safe >> files sync ./localfolder safe://mysite
Files will be uploaded recursively, is it ok? [Y/n]:
We will be updating 'mysite' NRS name as well, is it ok? [Y/n]:
This operation will cost ~ 0.000044523, is it ok to proceed? [y/N]:

Having those configs about expenditure could be also possible and a nice idea, perhaps that could be stored locally in a config file, or even within your SAFE account and the CLI reads if you are logged in.

Just in case you didn’t know, you can already try it out, and we’ve been using a shared vault also, so it’s not in the wild wild, but a bit wild :smiley: , if you weren’t aware look at this: New Release: Vault Phase 1 (real vault), the User Guide is up to date with latest version available (v0.3.0) and it’s here:


Hey @bochaco,
thanks for the swift and elaborate response. :+1:

Oh, I didn’t know about that option. Nice!

Yeah, I really like that idea. Although that would not fix the problem when running in non-interactive-mode (which is the more common case, I guess?).

Nice, I really like the idea of storing it in your SAFE account.:tada: Maybe in the first iteration we still have a separate config file for the CLI and in the second iteration we finally move the whole config over to the SAFE account.

Cool, thanks for the hint.
Man, I really have to catch up on SAFE. I haven’t been here in a while. But I guess that’s a very good sign that so much has happened since my last visit, so I am not complaining. :smile:


Another possibility if it is practical, would be for there to be a default max cost per command which would trigger a confirmation prompt, with the user able to override that limit with an environment variable.

A Safecoin cost might not be the best measure for this because the store cost could change dramatically as Safecoin value fluctuates, so the limit might be better expressed in storage operations.

I think we will want users to be able to set trigger cost limits in various scenarios, so addressing this in the CLI might help design a general approach.


Well it sounds like we have some nice things to explore and test here, although I presume this won’t be possible until we can estimate the cost of the operation/s somehow. So let’s see what we get from vaults when they evolve and we can test this as soon as it provides some type of estimation possible.

Well, we do have a complaint here, why have you been away for such a long time?? :smiley:


I wonder if we can find ways to bring the auth CLI request window to the front. Searching I found this for Linux:



What’s your opinion of replicating the cargo design of accepting subcommands? (GitHub - koute/cargo-web: A Cargo subcommand for the client-side Web for example)

An rsync subcommand could be separately offered that respects all rsync switches, enabling drop-in replacement without having to be directly implemented and maintained.

safe-cli does already accept subcommands, eg safe files ..., safe wallet ..., and so on.

From my perspective an rsync-esque sub-command is achievable, but perhaps overly ambitious for mvp, keeping in mind also that safe files sync exists.

1 Like

Implement this in the first upgrade, lets get the MVP out and then sort out the slashes


We have the files sync command which was originally thought to be like rsync, and we are now probably changing some bits as per feedback received. Are you on the contrary suggesting something more like being able to hook other tools, kinda plugins for the CLI which we wouldn’t need to maintain?



The latter to in part support the former.

The benefits to developing standard and optional subcommands separately from the core include:

  • Improves its quality and the developer experience.
  • Having the possibility of offering both a native (sync) and compatibility (rsync) subcommand is good. Moreover, there are several ‘eras’[0] of rsync in wide distribution, due to issues such as licensing, and supporting externally developed and maintained subcommands for interface variants would be trivial. (rsync26)
  • I can envision CLI subcommands as a useful extension point for those developing for SAFE.

[0] “rsync version 2.6.9 protocol version 29; Copyright (C) 1996-2006” is what’s included with macOS Mojave.

1 Like

Right, sounds cool, i think we should look at something like that in the future, it should also encourage devs and users to contribute to CLI as they can create these tools as they wish and users would just pick them up at their will expanding the SAFE ecosystem.



Indeed. I should probably also include that ideally their use would require a user consent registration mechanism, as SAFE app permissions do, in the installation process.

1 Like