keybase / keybase/client

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

Open
#23,787 9 comments 10 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

Dominant language
Go
Stars
9.2k
Forks
1.3k
Avg merge
12h 58m
Merged PRs (30d)
56

Description

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.)

Contributor guide

No contributing guide indexed for this repository

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with the keybase fs ls entry point and its help usage and argument errors, then compare the guidance in issue #15547. Document that KBFS paths use /keybase/private, /keybase/team, or /keybase/public, and clarify the expected number and form of path arguments and the resulting errors.

Written by the indexing model from the issue text.

Assessment

Tech stack
go
Domain
cli
Issue type
Documentation
Difficulty
3/5
Estimated time
1-2 days
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
45/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.