vagrant/website/source/docs/cli/cloud.html.md

layout	page_title	sidebar_current	description
docs	vagrant cloud - Command-Line Interface	cli-cloud	The "vagrant cloud" command can be used for taking actions against Vagrant Cloud like searching or uploading a Vagrant Box

Cloud

Command: vagrant cloud

This is the command used to manage anything related to Vagrant Cloud.

The main functionality of this command is exposed via subcommands:

• auth
• box
• provider
• publish
• search
• version

Cloud Auth

Command: vagrant cloud auth

The cloud auth command is for handling all things related to authorization with Vagrant Cloud.

• login
• logout
• whoami

Cloud Auth Login

Command: vagrant cloud auth login

The login command is used to authenticate with HashiCorp's Vagrant Cloud server. Logging in is only necessary if you are accessing protected boxes.

Logging in is not a requirement to use Vagrant. The vast majority of Vagrant does not require a login. Only certain features such as protected boxes.

The reference of available command-line flags to this command is available below.

Options

• --check - This will check if you are logged in. In addition to outputting whether you are logged in or not, the command exit status will be 0 if you are logged in, or 1 if you are not.

• --logout - This will log you out if you are logged in. If you are already logged out, this command will do nothing. It is not an error to call this command if you are already logged out.

• --token - This will set the Vagrant Cloud login token manually to the provided string. It is assumed this token is a valid Vagrant Cloud access token.

Examples

Securely authenticate to Vagrant Cloud using a username and password:

$ vagrant cloud auth login
# ...
Vagrant Cloud username:
Vagrant Cloud password:

Check if the current user is authenticated:

$ vagrant cloud auth login --check
You are already logged in.

Securely authenticate with Vagrant Cloud using a token:

$ vagrant cloud auth login --token ABCD1234
The token was successfully saved.

Cloud Auth Logout

Command: vagrant cloud auth logout

This will log you out if you are logged in. If you are already logged out, this command will do nothing. It is not an error to call this command if you are already logged out.

Cloud Auth Whomi

Command: vagrant cloud auth whoami [TOKEN]

This command will validate your Vagrant Cloud token and will print the user who it belongs to. If a token is passed in, it will attempt to validate it instead of the token stored stored on disk.

Cloud Box

Command: vagrant cloud box

The cloud box command is used to manage life cycle operations for all box entities on Vagrant Cloud.

• create
• delete
• show
• update

Cloud Box Create

Command: vagrant cloud box create ORGANIZATION/BOX-NAME

The box create command is used to create a new box entry on Vagrant Cloud.

Options

• --description DESCRIPTION - A full description of the box. Can be formatted with Markdown.
• --short-description DESCRIPTION - A short summary of the box.
• --private - Will make the new box private (Public by default)

Cloud Box Delete

Command: vagrant cloud box delete ORGANIZATION/BOX-NAME

The box delete command will permanently delete the given box entry on Vagrant Cloud. Before making the request, it will ask if you are sure you want to delete the box.

Cloud Box Show

Command: vagrant cloud box show ORGANIZATION/BOX-NAME

The box show command will display information about the latest version for the given Vagrant box.

Cloud Box Update

Command: vagrant cloud box update ORGANIZATION/BOX-NAME

The box update command will update an already created box on Vagrant Cloud with the given options.

Options

• --description DESCRIPTION - A full description of the box. Can be formatted with Markdown.
• --short-description DESCRIPTION - A short summary of the box.
• --private - Will make the new box private (Public by default)

Cloud Provider

Command: vagrant cloud provider

The cloud provider command is used to manage the life cycle operations for all provider entities on Vagrant Cloud.

• create
• delete
• update
• upload

Cloud Provider Create

Command: vagrant cloud provider create ORGANIZATION/BOX-NAME PROVIDER-NAME VERSION [URL]

The provider create command is used to create a new provider entry on Vagrant Cloud. The url argument is expected to be a remote URL that Vagrant Cloud can use to download the provider. If no url is specified, the provider entry can be updated later with a url or the upload command can be used to upload a Vagrant box file.

Cloud Provider Delete

Command: vagrant cloud provider delete ORGANIZATION/BOX-NAME PROVIDER-NAME VERSION

The provider delete command is used to delete a provider entry on Vagrant Cloud. Before making the request, it will ask if you are sure you want to delete the provider.

Cloud Provider Update

Command: vagrant cloud provider update ORGANIZATION/BOX-NAME PROVIDER-NAME VERSION [URL]

The provider update command will update an already created provider for a box on Vagrant Cloud with the given options.

Cloud Provider Upload

Command: vagrant cloud provider upload ORGANIZATION/BOX-NAME PROVIDER-NAME VERSION BOX-FILE

The provider upload command will upload a Vagrant box file to Vagrant Cloud for the specified version and provider.

Cloud Publish

Command: vagrant cloud publish ORGANIZATION/BOX-NAME VERSION PROVIDER-NAME [PROVIDER-FILE]

The publish command is a complete solution for creating and updating a Vagrant box on Vagrant Cloud. Instead of having to create each attribute of a Vagrant box with separate commands, the publish command instead asks you to provide all the information required before creating or updating a new box.

Options

• --box-version VERSION - Version to create for the box
• --description DESCRIPTION - A full description of the box. Can be formatted with Markdown.
• --force - Disables confirmation when creating or updating a box.
• --short-description DESCRIPTION - A short summary of the box.
• --private - Will make the new box private (Public by default)
• --release - Automatically releases the box after creation (Unreleased by default)
• --url - Valid remote URL to download the box file
• --version-description DESCRIPTION - Description of the version that will be created.

Examples

Creating a new box on Vagrant Cloud:

$ vagrant cloud publish briancain/supertest 1.0.0 virtualbox boxes/my/virtualbox.box -d "A really cool box to download and use" --version-description "A cool version" --release --short-description "Download me!"
You are about to create a box on Vagrant Cloud with the following options:
briancain/supertest (1.0.0) for virtualbox
Automatic Release:     true
Box Description:       A really cool box to download and use
Box Short Description: Download me!
Version Description:   A cool version
Do you wish to continue? [y/N] y
Creating a box entry...
Creating a version entry...
Creating a provider entry...
Uploading provider with file /Users/vagrant/boxes/my/virtualbox.box
Releasing box...
Complete! Published briancain/supertest
tag:                  briancain/supertest
username:             briancain
name:                 supertest
private:              false
downloads:            0
created_at:           2018-07-25T17:53:04.340Z
updated_at:           2018-07-25T18:01:10.665Z
short_description:    Download me!
description_markdown: A really cool box to download and use
current_version:      1.0.0
providers:            virtualbox

Cloud Search

Command: vagrant cloud search QUERY

The cloud search command will take a query and search Vagrant Cloud for any matching Vagrant boxes. Various filters can be applied to the results.

Options

• --json - Format search results in JSON.
• --page PAGE - The page to display. Defaults to the first page of results.
• --short - Shows a simple list of box names for the results.
• --order ORDER - Order to display results. Can either be desc or asc. Defaults to desc.
• --limit LIMIT - Max number of search results to display. Defaults to 25.
• --provider PROVIDER - Filter search results to a single provider.
• --sort-by SORT - The field to sort results on. Can be created, downloads , or updated. Defaults to downloads.

Examples

If you are looking for a HashiCorp box:

vagrant cloud search hashicorp --limit 5
| NAME                    | VERSION | DOWNLOADS | PROVIDERS                       |
+-------------------------+---------+-----------+---------------------------------+
| hashicorp/precise64     | 1.1.0   | 6,675,725 | virtualbox,vmware_fusion,hyperv |
| hashicorp/precise32     | 1.0.0   | 2,261,377 | virtualbox                      |
| hashicorp/boot2docker   | 1.7.8   |    59,284 | vmware_desktop,virtualbox       |
| hashicorp/connect-vm    | 0.1.0   |     6,912 | vmware_desktop,virtualbox       |
| hashicorp/vagrant-share | 0.1.0   |     3,488 | vmware_desktop,virtualbox       |
+-------------------------+---------+-----------+---------------------------------+

Cloud Version

Command: vagrant cloud version

The cloud version command is used to manage life cycle operations for all version entities for a box on Vagrant Cloud.

• create
• delete
• release
• revoke
• update

Cloud Version Create

Command: vagrant cloud version create ORGANIZATION/BOX-NAME VERSION

The cloud create command creates a version entry for a box on Vagrant Cloud.

Options

• --description DESCRIPTION - Description of the version that will be created.

Cloud Version Delete

Command: vagrant cloud version delete ORGANIZATION/BOX-NAME VERSION

The cloud delete command deletes a version entry for a box on Vagrant Cloud. Before making the request, it will ask if you are sure you want to delete the version.

Cloud Version Release

Command: vagrant cloud version release ORGANIZATION/BOX-NAME VERSION

The cloud release command releases a version entry for a box on Vagrant Cloud if it already exists. Before making the request, it will ask if you are sure you want to release the version.

Cloud Version Revoke

Command: vagrant cloud version revoke ORGANIZATION/BOX-NAME VERSION

The cloud revoke command revokes a version entry for a box on Vagrant Cloud if it already exists. Before making the request, it will ask if you are sure you want to revoke the version.

Cloud Version Update

Command: vagrant cloud version update ORGANIZATION/BOX-NAME VERSION

Options

• --description DESCRIPTION - Description of the version that will be created.