SAFE CLI - High Level Design Document

Fair point, one of the more intriguing unresolved’s.


I think I didn’t quite understand what is envisioned: Is safe-auth-cli in daemon mode a possible external authentication mechanism for safe-cli?

In this case I would be happy with this, as the whole thing is without GUI and can run on a headless system.

Would this also be true for programs written in another language (C#, NodeJs, …)?

Currently, they all need a Safe Browser running, meaning that they cannot run on a headless system. If they could connect to safe-auth-cli, that would solve this problem.

Then another flag will need to be added to safe-auth-cli to create an account. I mentioned invite parameter just to indicate that account creation is possible right now.

1 Like

That’s the aim yep. Right now you can run a simple http server to run Auth requests, but later on we’re aiming to provide a deamon option. So any language that can execute bash scripts, or http calls will be able to Auth / create accounts etc.

We’re aiming for as much as possible to be possible without a GUI.


Very interesting design document. I think a CLI is a very nice and welcomed addition for developers and users.

I’m thinking about the architectural side of the CLI. Taking the following into account:

As I understand it a new API will be built that is higher level than the current SCL interface. This new high-level interface will initially be built and designed by developing the CLI in tandem. And, as I interpret, the API could be used as an alternative to the SCL by programming languages other than Rust.

For other programming languages to interface with this API I assume it will have/be an FFI, just like the current SCL FFI that apps built upon. I’m not sure I like the idea of two separate FFIs, or will the new API be part of the current SCL suite?

I’ve spent my fair time studying the SCL FFI and while it is fairly complex as it is low-level-ish, I’m not sure what a high-level variant will look like.

A question from another angle: Why wouldn’t the CLI be implemented in something like Python using the current SCL FFI? If it appears to be difficult, the FFI can be adjusted to become more user friendly or more functions can be added that are higher level. The CLI written in Python will then be used as a kind of reference implementation showcasing the FFI. This would be in the form of well-documented idioms that could educate SAFE developers.
(I picked Python as I assume it’s one of the easier to understand languages without being proficient at it, in contrast to Rust.)


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? ( 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