help text for juju scp needs improving

[Peter Matulis]

Usage: juju scp [options] <file> [<user>@]<target>:[<path>]

Summary:
Transfers files to/from a Juju machine.

Options:

-m, --model (= "")
    Model to operate in
--proxy (= true)
    Proxy through the API server
--pty (= true)
    Enable pseudo-tty allocation

Details:
The usage is for transferring files from the client to a Juju machine. To do the reverse:
juju scp [options] [<user>@]<target>:<file> <path>
and use quotes when multiple files are involved.
The machine is identified by the <target> argument which is either a 'unit name' or a 'machine id'. Both are obtained in the output from `juju status`: unit name in the [Units] section and machine id in the [Machines] section.
If 'user' is specified then the connection is made to that user account; otherwise, the 'ubuntu' account is used.
'file' can be single or multiple files or directories. For directories, you must use the scp option of '-r'.
Options specific to scp can be inserted between 'scp' and '[options]' with '-- <scp-options>'. Refer to the scp(1) man page for an explanation of those options.

Examples:

Copy file /var/log/syslog from machine 2 to the client's current working directory:

    juju scp 2:/var/log/syslog .

Copy directory /var/log/mongodb, recursively, from a mongodb unit
to the client's local directory remote-logs:

    juju scp -- -r mongodb/0:/var/log/mongodb/ remote-logs

Copy file foo.txt, in verbose mode, from the client's current working directory to an apache2 unit of model "mymodel":

    juju scp -- -v -m mymodel foo.txt apache2/1:

Copy multiple files from the client's current working directory to machine 2:

    juju scp file1 file2 2:

Copy multiple files from the bob user account on machine 3 to the client's current working directory:

    juju scp bob@3:'file1 file2' .

See also: ssh

[Reed O'Brien (reedobrien)]

Usage here is multiline, and has content between the subcommand (scp) and [options]. Usage is dynamically generated and I am not sure exactly how to change it in this case without rewriting the juju/cmd package.

Please advise.

[Reed O'Brien (reedobrien)]

OUtput at this point would look like:

Usage: juju scp [options] [[user@]host1:]file1 ... [[user@]host2:]file2

Summary:
Transfers files to/from a Juju machine.

Options:
-m, --model (= "")
    Model to operate in
--proxy (= false)
    Proxy through the API server
--pty (= true)
    Enable pseudo-tty allocation

Details:
The machine is identified by the <target> argument which is either a 'unit
name' or a 'machine id'. Both are obtained in the output from `juju
status`: unit name in the [Units] section and machine id in the [Machines]
section.
If 'user' is specified then the connection is made to that user account;
otherwise, the 'ubuntu' account is used.
A 'file' can be an individual file or a directory. If the latter, you must
use the scp option of '-r'.
'file' can also be multiple files/directories. In the first usage do not
use quoting but in the second usage you must use quoting.
Refer to the scp(1) man page for an explanation of scp options.

Examples:
Copy file /var/log/syslog from machine 2 to the current working directory:

    juju scp 2:/var/log/syslog .

Copy directory /var/log/mongodb, recursively, from a mongodb unit
to local directory remote-logs:

    juju scp -- -r mongodb/0:/var/log/mongodb/ remote-logs

Copy file foo.txt, in verbose mode, from the current working directory to an apache2 unit of model "mymodel":

    juju scp -- -v -m mymodel foo.txt apache2/1:

See also:
    ssh

[Peter Matulis (petermatulis)]

@Reed
Updated description

[Nick Veitch (evilnick)]

Hmm. this doesn't solve the <scp-options> bit not appearing in usage, which I guess will be left out.

It will have to do. We will need to circle back after release and work out how to generate these more correctly and sensibly - the current output has too many restrictions!

[Peter Matulis (petermatulis)]

I updated again to insert a workaround.

[Reed O'Brien (reedobrien)]

I am just learning about the cmd package. I'd be happy to talk about improvements to it after 2.0.

[Reed O'Brien (reedobrien)]

Updated output:

Usage: juju scp [options] <file> [<user>@]<target>:[<path>]

Summary:
Transfers files to/from a Juju machine.

Options:
-m, --model (= "")
    Model to operate in
--proxy (= false)
    Proxy through the API server
--pty (= true)
    Enable pseudo-tty allocation

Details:
The usage is for transferring files from the client to a Juju machine. To
do the reverse:
juju scp [options] [<user>@]<target>:<file> <path>
and use quotes when multiple files are involved.
The machine is identified by the <target> argument which is either a 'unit
name' or a 'machine id'. Both are obtained in the output from `juju
status`: unit name in the [Units] section and machine id in the [Machines]
section.
If 'user' is specified then the connection is made to that user account;
otherwise, the 'ubuntu' account is used.
A 'file' can be an individual file or a directory. If the latter, you must
use the scp option of '-r'.
Options specific to scp can be inserted between 'scp' and '[options]' with
'-- <scp-options>'. Refer to the scp(1) man page for an explanation of
those options.

Examples:
Copy file /var/log/syslog from machine 2 to the client's current working
directory:

    juju scp 2:/var/log/syslog .

Copy directory /var/log/mongodb, recursively, from a mongodb unit
to the client's local directory remote-logs:

    juju scp -- -r mongodb/0:/var/log/mongodb/ remote-logs

Copy file foo.txt, in verbose mode, from the client's current working
directory to an apache2 unit of model "mymodel":

    juju scp -- -v -m mymodel foo.txt apache2/1:

Copy multiple files from the client's current working directory to machine
2:

    juju scp file1 file2 2:

Copy multiple files from the bob user account on machine 3 to the client's
current working directory:

    juju scp bob@3:'file1 file2' .

See also:
    ssh

[Peter Matulis (petermatulis)]

Somehow, this line is not in your last comment:

'file' can be single or multiple files or directories. For directories, you must use the scp option of '-r'.

[Reed O'Brien (reedobrien)]

Not sure how:( Here's what is in there. Maybe I had a stale copy on my clipboard:

Usage: juju scp [options] <file> [<user>@]<target>:[<path>]

Summary:
Transfers files to/from a Juju machine.

Options:
-m, --model (= "")
    Model to operate in
--proxy (= false)
    Proxy through the API server
--pty (= true)
    Enable pseudo-tty allocation

Details:
The usage is for transferring files from the client to a Juju machine. To
do the reverse:
juju scp [options] [<user>@]<target>:<file> <path>
and use quotes when multiple files are involved.
The machine is identified by the <target> argument which is either a 'unit
name' or a 'machine id'. Both are obtained in the output from `juju
status`: unit name in the [Units] section and machine id in the [Machines]
section.
If 'user' is specified then the connection is made to that user account;
otherwise, the 'ubuntu' account is used.
'file' can be single or multiple files or directories. For directories,
you must use the scp option of '-r'.
Options specific to scp can be inserted between 'scp' and '[options]' with
'-- <scp-options>'. Refer to the scp(1) man page for an explanation of
those options.

Examples:
Copy file /var/log/syslog from machine 2 to the client's current working
directory:

    juju scp 2:/var/log/syslog .

Copy directory /var/log/mongodb, recursively, from a mongodb unit
to the client's local directory remote-logs:

    juju scp -- -r mongodb/0:/var/log/mongodb/ remote-logs

Copy file foo.txt, in verbose mode, from the client's current working
directory to an apache2 unit of model "mymodel":

    juju scp -- -v -m mymodel foo.txt apache2/1:

Copy multiple files from the client's current working directory to machine
2:

    juju scp file1 file2 2:

Copy multiple files from the bob user account on machine 3 to the client's
current working directory:

    juju scp bob@3:'file1 file2' .

See also:
    ssh