vagrant-upload

Upload file or directory from the host to the guest machine

$ vagrant upload [path/to/source_file_or_directory] [path/to/destination_file_or_directory] [name|id]

$ vagrant upload --compress [path/to/source_file_or_directory] [path/to/destination_file_or_directory] [name|id]

$ vagrant upload --compression-type [tgz|zip] [path/to/source_file_or_directory] [path/to/destination_file_or_directory] [name|id]

$ vagrant upload --temporary [path/to/source_file_or_directory] [path/to/destination_file_or_directory] [name|id]

vagrant upload [options] [<machine-name>] <src> <dest>

<machine-name>: The name of the guest machine to upload to. If omitted and only one machine is defined, it will be used.
<src>: The path to the file or directory on the host machine to upload.
<dest>: The destination path on the guest machine where the files will be placed.

-h, --help
    Prints a helpful usage message and exits.

-r, --recursive
    Uploads directories recursively, copying all their contents and subdirectories.

-u USER, --upload-as USER
    Specifies the user on the guest machine under which the files should be uploaded.

-k, --keep-owners
    Attempts to preserve the original file owners and groups from the host on the guest machine. This often requires sudo privileges on the guest to execute chown commands.

--ssh-opts OPTS
    Passes additional SSH options directly to the underlying scp command. For example, -P 2222 for specific port forwarding.

--host HOST
    If a single Vagrant machine definition has multiple guests (e.g., using a multi-machine setup), this option allows specifying which host to connect to for the upload.

--port PORT
    Similar to --host, this specifies the port for connecting to a particular guest in a multi-guest machine configuration.

The vagrant upload command provides a convenient way to transfer files or directories from your host machine to a running Vagrant guest machine. It abstracts away the complexities of manual scp commands by automatically determining the guest's connection details (IP address, SSH port, username, private key). This command is particularly useful for quickly deploying configuration files, scripts, or application code to your development environment without needing to SSH into the VM first.

It supports recursive uploads for directories and offers options for specifying target users and preserving file ownership, making it an essential tool for streamlining file synchronization within your Vagrant-managed environments.

• The guest machine must be running and accessible via SSH for vagrant upload to function.
• Permissions on the guest machine might prevent uploads to certain directories unless the --upload-as option is used with a privileged user or the target directory is writable by the default vagrant user.
• The --keep-owners option typically requires sudo privileges on the guest machine for the Vagrant user to successfully execute chown and chgrp commands.
• This command is specifically for uploading files from the host to the guest. For downloading files from the guest, you would need to use vagrant scp or the direct scp command.
• Large file transfers can be slow depending on network conditions and VM performance.

Under the hood, vagrant upload leverages the Secure Copy Protocol (SCP) over SSH. It automatically uses the SSH connection details configured by Vagrant for the specified guest machine, including the private key and forwarded port, eliminating the need for manual configuration and making file transfers seamless within the Vagrant ecosystem.

The vagrant upload command was introduced in Vagrant to simplify the common task of transferring files to a guest VM. Prior to its introduction, users often had to manually construct complex scp commands, which required looking up the VM's dynamic SSH port, IP address, and private key path. This command streamlined the development workflow by providing a more user-friendly and automated interface for host-to-guest file synchronization, directly integrating with Vagrant's machine management capabilities.

vagrant ssh(1), vagrant scp(1), scp(1), ssh(1)