"KBFS path arguments" to `keybase fs` commands under-documented

[OJFord]

I couldn't work out how to call e.g. keybase fs ls until I found #15547, after having read the help, scoured the website docs, and read the code (as someone who's barely written Go).

The help usage is:

    keybase fs ls [command options] <path>

and the error when you don't give a <path> is:

Error parsing command line arguments: ls requires at least one KBFS path argument

A better error would include an explanation of what a 'KBFS path argument' is, i.e. that it must start /keybase/private or /keybase/team or /keybase/public.

Perhaps the usage should even be /keybase/(private|team|public)[PATH] instead of <path>.

Further, the 'at least one' in the error message appears to be wrong; supplying two independently valid KBFS path arguments results in the error:

ERROR file does not exist

I would guess because it's taking it as one path with a space in the middle.

Supplying just /keybase gives:

ERROR RootFS cannot chroot

which could be problematic for using /keybase/teams, since I believe that sub-directory doesn't exist until one joins a team.

For what it's worth, the /keybase seems redundant to me, and what I was guessing at before I found out how to call it was variations on what turned out to be valid, just without that prefix. (And then the full path to the real location, just in case the command didn't do what I thought/was hoping.)

[jpaugh]

Same thing happened to me. I was trying to use /kbfs/ and K:\. FWIW, the syntax is intuitive enough on Linux, where /keybase corresponds to the filesystem location where KBFS is mounted, and tab-completion works.

[bartenbach]

Yeah, this is one of the least intuitive things I've seen in a while. It's not clear at all how this works and the error messages are not helpful.

% keybase fs ls /
Error parsing command line arguments: ls requires KBFS path arguments

What is a KBFS path argument?

% keybase fs ls /keybase
▶ ERROR EOF
zsh: exit 2     keybase fs ls /keybase

I still have no idea what this wants. Where is the root of this filesystem? Just tell me what you want, keybase.

~/doc
% keybase fs mkdir test

~/doc
% ls
test/ 

~/doc
% keybase fs ls test
Error parsing command line arguments: ls requires KBFS path arguments

NAME:
   keybase fs ls - list directory contents

USAGE:
   keybase fs ls [command options] <path>

OPTIONS:
   --rec, --recursive       recurse into subdirectories
   --nocolor            remove color formatting
   -1, --one            one entry per line
   -a, --all            include entries starting with '.'
   -l, --long           long listing
   -r, --sort-reverse       reverse any sorting
   -t, --sort-time      sort entries by modify time
   -s, --sort-size      sort entries by size
   -w, --windows        windows style dir
   --rev "0"            a revision number for the KBFS folder
   --time           a time for the KBFS folder (eg "2018-07-27 22:05")
   --reltime, --relative-time   a relative time for the KBFS folder (eg "5m")

zsh: exit 2     keybase fs ls test

~/doc
% keybase fs ls /keybase/test
▶ ERROR EOF
zsh: exit 2     keybase fs ls /keybase/test

~/doc
% keybase fs ls /test
Error parsing command line arguments: ls requires KBFS path arguments

I think I can guess every possible way to use this except how it wants to be used. I can make directories but cannot list the contents.

[bartenbach]

Update: so apparently after some reading, starting the systemd user unit is not enough. You then have to run the run_keybase executable. That seems to start it up, at which point it still doesn't work:

[GwynethLlewelyn]

Oh... so that's what a 'KBFS path argument' is.

Well, well, I totally agree that this ought to be better documented. Or, rather, documented. Period. It is not :)

And I actually suspect why it isn't. You see, different operating systems have different ways of mounting the filesystem, so the 'KBFS path argument' will depend on how exactly your filesystem got mounted. I'm just saying that because I've just tested: on macOS, if the Fuse kernel extension is not running (I seem to have a conflict somewhere preventing it to launch properly), then the command-line keybase fs ls <path> will not work.

That is counter-intuitive by itself — I thought that the whole point of using keybase fs ls <path> was to sidestep any issues during the weird mounting phase (which will often hiccup, or not work at all, or only sporadically...). Apparently, the CLI tool relies on the filesystem being properly mounted, on the 'expected' place for your operating system. Argh!

[JoNilsson]

BUMP!

[GwynethLlewelyn]

Thanks for that much-needed bump!

Actually, let me correct myself. On macOS, even if the KBFS is not mounted, you nevertheless can do

keybase fs ls /keybase/public/

and it will still work. Assuming you're logged in, of course!

[ChicagoGregg]

I was looking for more information on this today as well.

I ran into the following link that provides some information on this:

https://gist.github.com/scottrigby/9c03b0db6100285d5b032b87fac00b8a

It suggests the following commands. I still agree the documentation for this is limited.

$ keybase fs ls /Volumes/Keybase/team/$TEAM/
foo.com.saltpack
$ keybase fs read /Volumes/Keybase/team/$TEAM/foo.com.saltpack | keybase decrypt