Skip to content
Tutorials Center
My learning

Topics

Lesson 4 of 36 Β· Getting Started

CLI Essentials and the Machine Lifecycle

Learn the everyday Vagrant commands: up, halt, suspend, resume, reload, status, global-status, snapshots and destroy, and how machine states change.

You already know up, ssh, halt and destroy. Daily work with Vagrant needs a few more: suspending a machine to save its memory state, reloading after you edit the Vagrantfile, checking which machines exist across your whole computer, and taking snapshots before risky changes. This lesson gives you the full everyday command set and a mental model for the states a machine moves through.

The states of a machine

At any moment a machine is in one state, and vagrant status tells you which:

CONSOLE
$ vagrant status
Current machine states:

default                   running (virtualbox)

The VM is running. To stop this VM, you can run `vagrant halt` to
shut it down, or you can run `vagrant suspend` to simply suspend
the virtual machine. In either case, to restart it again, run
`vagrant up`.

The common states are not created, running, poweroff (also called stopped), saved (suspended) and aborted (the VM crashed or was killed). The diagram shows how the main commands connect them.

stateDiagram-v2
    [*] --> not_created
    not_created --> running: up
    running --> poweroff: halt
    poweroff --> running: up
    running --> saved: suspend
    saved --> running: resume / up
    running --> not_created: destroy
    poweroff --> not_created: destroy
    saved --> not_created: destroy
    running --> running: reload

Every command is a transition between states.

The core commands

Start and stop

vagrant up Create or start
vagrant halt Graceful shutdown
vagrant suspend Save RAM to disk
vagrant resume Wake a saved VM
1 / 2

vagrant up creates the machine if needed or starts it if it exists. If the machine is already running, it does nothing (except it can run provisioners that did not run yet, see Provisioning).

vagrant halt sends an ACPI shutdown, like pressing the power button once, and waits. Use vagrant halt -f to force power-off when the guest hangs.

vagrant suspend / vagrant resume save the VM's memory to disk and freeze it. Resuming takes seconds and brings your open programs back, but the saved state uses disk space equal to the VM's RAM. Use halt to free that space.

vagrant reload is halt followed by up. You need it whenever you change machine hardware settings in the Vagrantfile: memory, CPUs, network adapters, synced folders. Add --provision to re-run the provisioners at the same time.

vagrant destroy deletes the VM and its disks. It asks for confirmation; -f skips that. Combined with up it is the classic "start clean" loop:

CONSOLE
$ vagrant destroy -f && vagrant up

vagrant ssh -c "command" runs one command in the guest and returns, which is perfect for scripts: vagrant ssh -c "systemctl status nginx".

Machines on your whole computer

vagrant status only looks at the current folder. To list every Vagrant machine that you created anywhere, use:

CONSOLE
$ vagrant global-status
id       name    provider   state   directory
-----------------------------------------------------------------
a1b2c3d  default virtualbox running /home/you/hello-vagrant
e4f5a6b  web     virtualbox poweroff /home/you/shop

The id lets you control a machine from any folder: vagrant halt a1b2c3d. If the list contains machines whose folders were deleted, run vagrant global-status --prune to clean the index. This command is also how you find forgotten VMs that quietly eat RAM.

Snapshots

A snapshot saves the exact state of the VM so you can return to it later: take one before a risky upgrade, then roll back if it breaks.

CONSOLE
$ vagrant snapshot save clean-install
$ vagrant snapshot list
clean-install
$ vagrant snapshot restore clean-install
$ vagrant snapshot delete clean-install

There is also vagrant snapshot push and pop, a stack-based pair for quick experiments. Snapshots consume disk space and slow the VM a little as they pile up, so they are a short-term tool, not a backup. For a reproducible clean state, destroy plus up plus provisioning is better.

Other useful commands

Command What it does
vagrant validate Checks the Vagrantfile for errors without starting anything
vagrant port Shows forwarded ports of the running machine
vagrant provision Re-runs provisioners on a running machine
vagrant ssh-config Prints the SSH settings (for other SSH clients)
vagrant box list Lists cached boxes, see Managing boxes
vagrant plugin list Lists installed plugins
vagrant version Shows the installed and latest versions
vagrant help <command> Detailed help for any command

Commands accept a machine name when the Vagrantfile defines several (vagrant up web), see the Multi-machine chapter of this track. Most commands also take --debug, which prints a very detailed log; set VAGRANT_LOG=info in the environment for a lighter log.

A command parser stand-in

The runnable example is a stand-in: a tiny Ruby model that decides which state each command leads to, and refuses commands that make no sense. It shows how a CLI with a state table behaves, including a snapshot stack.

Ruby Commands, states and snapshots (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input Β· what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with gets), it gets the next line from this box.

Habits that save time

  • Use vagrant validate after editing the file; typos in Ruby show up immediately.
  • Use halt at the end of the day, not suspend, if disk space is tight.
  • Run vagrant global-status once a week to find forgotten machines.
  • Prefer vagrant reload --provision over manual fixes inside the guest, so the Vagrantfile stays the source of truth.

Check your understanding

Quick check Β· 4 questions

of 4 answered You scored / 4 Β· perfect!

  1. 1. When do you need vagrant reload?

    Reload restarts the VM so that changed hardware, network and synced folder settings are applied.
  2. 2. What is the difference between halt and suspend?

    Suspend keeps the running state (and uses disk equal to RAM); halt performs a normal shutdown.
  3. 3. Which command lists all Vagrant machines on your computer?

    status is per project, box list shows boxes, and global-status lists machines everywhere.
  4. 4. What does vagrant snapshot restore clean do?

    A snapshot stores the VM state; restore rolls back to it.

Summary

  • vagrant status shows the state; commands move a machine between not created, running, poweroff and saved.
  • reload applies hardware changes; provision re-runs setup; destroy followed by up rebuilds from scratch.
  • global-status finds every machine on the computer; --prune cleans stale entries.
  • Snapshots are for short-term rollback, not backups.
  • vagrant validate and vagrant help catch mistakes early.

Next: Vagrantfile Basics