Commands · reference
vmlab cp
vmlab cp copies a file or a tree between the host and a guest over the vmlab agent's file session, with no guest network and no share involved. Either side may be a guest reference spelled <vm>:<path>; the other is a host path. Parent directories on the receiving side are created.
| Option | Meaning |
|---|---|
| <SRC> | Source: a host path, or <vm>:<path> to pull from the guest. |
| <DEST> | Destination: <vm>:<path> to push, or a host path when pulling. |
| -h, --help | Print help. |
The guest side is recognised by splitting on the first colon, so a Windows path keeps its drive letter: box:C:/weave is the machine box and the guest path C:/weave. The <vm> part accepts the [lab/]name form. When neither side is a guest reference the command is refused locally. A push whose host source does not exist is refused before any request is sent.
A push sends one file, or walks a directory and sends every file under it to the matching path below the guest destination, one request per file, keeping each file's mode. The daemon opens the host file itself, so the path is made absolute first, and verifies the digest end to end. It prints pushed <bytes> bytes to <vm>:<path> for a file and pushed <n> file(s), <bytes> bytes to <vm>:<path> for a tree.
A pull copies one guest file to the host path. When the host destination is an existing directory the guest file's name is kept under it. It prints pulled <bytes> bytes to <path>.
Transfers run as the agent identity
cp still runs as SYSTEM or root even on a machine that declares a login {}, unlike exec and shell. A pushed file is owned by the agent identity, not by the login shell would land you as. To write into a login's home as that login, use the as_login handle in a provision script (see Logins).
Exit status is 0 on success. not_found (4) means the lab declares no machine by that name. failed (1) covers a machine that is not running, an agent that does not answer, a guest path that cannot be opened, and a digest mismatch. A malformed pair of arguments or a missing host source exits 1 before any request is sent.