Improve bosh scp -h

[ragaskar]

• It is non-obvious how to compose remote path references for the bosh scp command. This change provides a minimal example of a remote path reference (:/some/remote/path) when help for scp is invoked. This example should be sufficient to allow a user to guess at what this command wants in order to target a remote path. It directs users to the documentation for further examples (as there are some other "special" parameters one can use with these path arguments that are not enumerated in the CLI help).

Below is an example of the current help for PATH, followed by the new display after this patch is applied:

Existing help:

Usage:
  bosh [OPTIONS] scp [scp-OPTIONS] PATH...

SCP to/from instance(s)

https://bosh.io/docs/cli-v2#scp

Application Options:
  -v, --version                Show CLI version
      --config=                Config file path (default: ~/.bosh/config) [$BOSH_CONFIG]
  -e, --environment=           Director environment name or URL [$BOSH_ENVIRONMENT]
      --ca-cert=               Director CA certificate path or value [$BOSH_CA_CERT]
      --sha2                   Use SHA256 checksums [$BOSH_SHA2]
      --parallel=              The max number of parallel operations (default: 5)
      --client=                Override username or UAA client [$BOSH_CLIENT]
      --client-secret=         Override password or UAA client secret [$BOSH_CLIENT_SECRET]
  -d, --deployment=            Deployment name [$BOSH_DEPLOYMENT]
      --column=                Filter to show only given column(s), use the --column flag for each column you wish to include
      --json                   Output as JSON
      --tty                    Force TTY-like output [$BOSH_TTY]
      --no-color               Toggle colorized output
  -n, --non-interactive        Don't ask for user input [$BOSH_NON_INTERACTIVE]

Help Options:
  -h, --help                   Show this help message

[scp command options]
      -r, --recursive          Recursively copy entire directories. Note that symbolic links encountered are followed in the tree traversal
      -i, --private-key=       SSH using authorized key
      -l, --username=          Login name for authorized key (default: vcap)
          --gw-disable         Disable usage of gateway connection [$BOSH_GW_DISABLE]
          --gw-user=           Username for gateway connection [$BOSH_GW_USER]
          --gw-host=           Host for gateway connection [$BOSH_GW_HOST]
          --gw-private-key=    Private key path for gateway connection [$BOSH_GW_PRIVATE_KEY]
          --gw-socks5=         SOCKS5 URL [$BOSH_ALL_PROXY]
          --director           Target the command at the BOSH director (or other type of VM deployed via create-env)
          --agent-endpoint=    Address to connect to the agent's HTTPS endpoint (used with --director) [$BOSH_AGENT_ENDPOINT]
          --agent-certificate= CA certificate to validate the agent's HTTPS endpoint (used with --director) [$BOSH_AGENT_CERTIFICATE]

Proposed Update

(see PATH near end of output)

Usage:
  bosh [OPTIONS] scp [scp-OPTIONS] PATH...

SCP to/from instance(s)

https://bosh.io/docs/cli-v2#scp

Application Options:
  -v, --version                Show CLI version
      --config=                Config file path (default: ~/.bosh/config) [$BOSH_CONFIG]
  -e, --environment=           Director environment name or URL [$BOSH_ENVIRONMENT]
      --ca-cert=               Director CA certificate path or value [$BOSH_CA_CERT]
      --sha2                   Use SHA256 checksums [$BOSH_SHA2]
      --parallel=              The max number of parallel operations (default: 5)
      --client=                Override username or UAA client [$BOSH_CLIENT]
      --client-secret=         Override password or UAA client secret [$BOSH_CLIENT_SECRET]
  -d, --deployment=            Deployment name [$BOSH_DEPLOYMENT]
      --column=                Filter to show only given column(s), use the --column flag for each column you wish to include
      --json                   Output as JSON
      --tty                    Force TTY-like output [$BOSH_TTY]
      --no-color               Toggle colorized output
  -n, --non-interactive        Don't ask for user input [$BOSH_NON_INTERACTIVE]

Help Options:
  -h, --help                   Show this help message

[scp command options]
      -r, --recursive          Recursively copy entire directories. Note that symbolic links encountered are followed in the tree traversal
      -i, --private-key=       SSH using authorized key
      -l, --username=          Login name for authorized key (default: vcap)
          --gw-disable         Disable usage of gateway connection [$BOSH_GW_DISABLE]
          --gw-user=           Username for gateway connection [$BOSH_GW_USER]
          --gw-host=           Host for gateway connection [$BOSH_GW_HOST]
          --gw-private-key=    Private key path for gateway connection [$BOSH_GW_PRIVATE_KEY]
          --gw-socks5=         SOCKS5 URL [$BOSH_ALL_PROXY]
          --director           Target the command at the BOSH director (or other type of VM deployed via create-env)
          --agent-endpoint=    Address to connect to the agent's HTTPS endpoint (used with --director) [$BOSH_AGENT_ENDPOINT]
          --agent-certificate= CA certificate to validate the agent's HTTPS endpoint (used with --director) [$BOSH_AGENT_CERTIFICATE]

[scp command arguments]
  PATH:                        Strings referencing remote (e.g. ":/some/remote/path" -- "user@host" may be omitted) or local paths (e.g. "./some/local/path"). See CLI documentation for more examples.

[selzoc]

I think it would be helpful to have an example of the more common case of scping from an instance/index or something

[ragaskar]

I think it would be helpful to have an example of the more common case of scping from an instance/index or something

I agree, not sure this is the right place for it?

I think there's no existing hooks for invocation examples, and shoving a full invocation example into an argument description feels a bit weird to me.

The problem I was trying to solve here is I was like "OK, I know I want to bosh scp, and I'm familiar with scp, but how does this work when I don't have the username/host -- what am I supposed to do?". I think the remote path example provides enough of a hint to let you solve that problem.

That said, my use case was director-tied (I was trying to bosh scp --director :/some/remote/file ./to/my/local), and so if the remote path example is flat-out wrong for the common case of scp-ing from an instance, than I agree, it should be changed.

[selzoc]

Right, in non-director cases it would be something like bosh scp diego-cell/0:/results.json /tmp

[a-hassanin]

Actually IMHO I would rather name it differently:
Usage:
bosh [OPTIONS] scp [scp-OPTIONS] source ... target

The same way a typical scp command would also describe it. I see it is technically one array, but it better describes how it can actually be used

[rkoster]

@ragaskar do you have any opinion on this?

[aramprice]

@ragaskar - are you ok with switching the the scp style documentation, instead of the example-based version in this PR?

[aramprice]

@ragaskar - can you fix the lint errors?

[rkoster]

@aramprice are you okey with merging now that the checks are passing?