client.ls for current directory

[BobDickinson]

I'm new to Manta. I was trying to list to contents of the root directory of my storage using client.ls().

I tried the example code from the docs:

client.ls('/', opts, function (err, res) {
    assert.ifError(err);
    ....
    });
});

And that produced:

{ [InvalidPathError: / is not a valid Manta path]
  name: 'InvalidPathError',
  message: '/ is not a valid Manta path' }

I also tried using '.' as well as an empty string and null, and none of them were considered a valid Manta path. From the command line I can do:

mls .

And that works fine.

So the docs say use '/' which doesn't work. The command line implies '.', but that also doesn't work in the client api. I took me a while to figure out to use "~~/stor/" (but that's kind of cheating if you ask me - assuming the client is rooted there and everything is relative to that, I shouldn't need to know that bit of magic to list the root contents).

Am I missing something?

[davepacheco]

Sorry that you ran into these bumps. It's a bug in the documentation that you didn't find the appropriate docs about Manta paths. They're documented here:
https://apidocs.joyent.com/manta/storage-reference.html#directories

There are several things going on here:

• Because Manta has a single global namespace for all data (across all accounts), all paths begin with a user account. For example, your account's private storage is at "/:account_name/stor".
• We do not let you list other user accounts, so the special case of "/" is not a valid path. (Hopefully it's clear why null and the empty string are invalid.)
• Unlike the shell, the CLI tools don't really have a notion of current working directory. The expectation (mine, anyway) is that you always provide a full path. As a convenience, some CLI tools allow you to use "~~" in place of "/:account/stor", but that's just sugar, and it's not consistent. See command line path handling is inconsistent #249 for a bug related to that.
• Since there's no notion of a current directory, I'm surprised "mls ." worked at all. That seems like a bug, but likely not one we can fix without a major version bump, since external programs might now depend on it.

In short, the documentation could use some work here, and the CLI tools' inconsistency doesn't help new users. But if you think of everything as an absolute path, optionally using "~~" as a shortcut for your private storage directory, the experience should be pretty smooth.

I'm leaving this ticket open to cover the task of fixing up the docs.