Waypoint Commands (CLI)

Waypoint is controlled via a very easy to use command-line interface (CLI). Waypoint is only a single command-line application: `waypoint`. This application then takes a subcommand such as `artifact` or `deployment`.

Warning

This content is part of the legacy version of Waypoint that is no longer actively maintained. For additional information on the new vision of Waypoint, check out this blog post and the HCP Waypoint documentation.

Waypoint is controlled via a very easy to use command-line interface (CLI). Waypoint is only a single command-line application: waypoint. This application then takes a subcommand such as artifact or deployment. The complete list of subcommands is in the navigation to the left.

The waypoint CLI is a well-behaved command line application. In erroneous cases, a non-zero exit status will be returned. It also responds to -h and --help as you'd most likely expect.

To view a list of the available commands at any time, just run waypoint with no arguments:

$ waypoint
Usage: waypoint [-version] [-help] [-autocomplete-(un)install] <command> [args]

Common commands:
    build        Build a new versioned artifact from source
    deploy       Deploy a pushed artifact
    release      Release a deployment
    up           Perform the build, deploy, and release steps

Other commands:
    artifact        Artifact and build management
    auth-method     Auth method management
    config          Application configuration management
    context         Server access configurations
    deployment      Deployment creation and management
    destroy         Delete all the resources created
    docs            Show documentation for components
    exec            Execute a command in the context of a running application instance
    fmt             Rewrite waypoint.hcl configuration to a canonical format
    hostname        Application URLs
    init            Initialize and validate a project
    install         Install the Waypoint server to Kubernetes, Nomad, or Docker
    logs            Show log output from the current application deployment
    project         Project management
    runner          Runner management
    server          Server management
    ui              Open the web UI
    user            User information and management
    version         Prints the version of this Waypoint CLI

To get help for any specific command, pass the -h flag to the relevant subcommand. For example, to see help about the up subcommand:

$ waypoint up -h
Usage: waypoint up [options]

  Perform the build, deploy, and release steps.

Global Options:

  -app=<string>
      App to target. Certain commands require a single app target for Waypoint
      configurations with multiple apps. If you have a single app, then this
      can be ignored. This is aliased as "-a".

  -plain
      Plain output: no colors, no animation. The default is false.

  -project=<string>
      Project to target. This is aliased as "-p".

  -workspace=<string>
      Workspace to operate in. This is aliased as "-w".

Operation Options:

  -label=<key=value>
      Labels to set for this operation. Can be specified multiple times.

  -local
      True to use a local runner to execute the operation, false to use a
      remote runner. If unset, Waypoint will automatically determine where the
      operation will occur, defaulting to remote if possible.

  -remote-source=<key=value>
      Override configurations for how remote runners source data. This is
      specified to the data source type being used in your configuration. This
      is used for example to set a specific Git ref to run against.

  -var=<key=value>
      Variable value to set for this operation. Can be specified multiple
      times.

  -var-file=<string>
      HCL or JSON file containing variable values to set for this operation.
      If any "*.auto.wpvars" or "*.auto.wpvars.json" files are present, they
      will be automatically loaded.

Command Options:

  -prune
      Prune old unreleased deployments. The default is true.

  -prune-retain=<int>
      The number of unreleased deployments to keep. If this isn't set or is
      set to any negative number, then this will default to 1 on the server.
      If you want to prune all unreleased deployments, set this to 0. The
      default is -1.

Running waypoint -autocomplete-install will add the waypoint autocomplete capability so you can do waypoint <tab> on commands. Running waypoint -autocomplete-uninstall will remove it. Please note that this will modify your shell init script, so you will need to reload your shell.