Get started using the wvs Command Line (CLI) tool

The wvs command line tool lets you use WVS through a command line interface.

Install the wvs CLI

The wvs CLI is installed when you install the WVS Desktop Client.

Initialize the wvs CLI

After the wvs CLI is installed, you must initialize it before you can use it to run commands.

To initialize the wvs CLI, run the following command in a terminal window: 

wvs authenticate

The command opens a browser window or tab that asks you to log in using your WVS credentials. After you’re logged in, you can close the browser window or tab.

Get started using the wvs CLI

This section contains tasks that help you get started using the wvs CLI.

List the available commands

To list the commands available in the wvs CLI, run the following command: 

wvs

The command returns something like the following: 

C:\wvs

This WVS command line interface provides commands for a number of varied
tasks, including:

    - Performing regular repository operations
        - Adding and configuring flows
        - Performing passthrough git operations
        - Miscellaneous validating  and admin tasks

The functionality provided by this CLI is grouped into a number of top level
commands which can be viewed simply by entering  the 'wvs' command with no
paramaters. The list of subcommands available for each can be viewed by
entering:

wvs <subcommand> --help

Usage:
  wvs [command]

Available Commands:
  authenticate Enter required authentication information
  branch       Shows help messages for all branch commands
  changelist   Shows help messages for all changelist commands
  completion   Generate the autocompletion script for the specified shell
  flow         Shows help messages for all flow commands
  gendocs      Generates markdown documentation for all commands.
  git          Passthrough command for invoking git commands
  goto         Shows help messages for all goto commands
  help         Help about any command
  project      Shows help messages for all project commands
  validate     Set of commands for validating and verifying projects
  version      Display the version of this software.

Flags:
  -h, --help   help for wvs

Use "wvs [command] --help" for more information about a command.
OK

C:\wvsProjects\hello-world-unity-mobile>

Work on an existing project

To run commands for an existing project, navigate to the project directory. Check information about the project by running the following command: 

wvs project status

The command returns something like the following: 

C:\wvsProjects\hello-world-unity-mobile>wvs project status
    PROJECT DEFINITION:
        Project Name:          hello-world-unity-mobile
        Project Description:   This is the community project of Unity Hello World for iOS and Android
        Push Branch:           main
    CURRENT CHANGELIST:
        <none>
    CHANGES:
        <none>
    FILES IN CHANGELIST (locked):
        <none>
OK

C:\wvsProjects\hello-world-unity-mobile>_

Clone a remote project

If you were invited by a team member with a remote project or you already have your own remote project and want to clone locally, with the WVS CLI, take a look at our CLI documentation on cloning.

Create or import a project

If you don’t already have a project in WVS, you have two options:

  • Create a new project.
  • Import an external project into WVS as a WVS project.

Create a new project

To create a new project, create an empty directory and run the following command: 

wvs project create --name "PROJECT_NAME" --template "TEMPLATE_NAME"

Replace the following:

  • PROJECT_NAME with the name you want to give to the project on WVS.

  • TEMPLATE_NAME with the name of the template that you want to use for the project.

    To get a list of templates, run the following command: 

    wvs project create --list

    The command returns something like the following: 

    C:\wvsProjects>wvs project create --list
template_blank_unreal
template_blank_unity
import
template_blank_generic
template_empty
blank
OK

C:\wvsProjects>_

Example:

To create a project in the wvsProjects\\MyProjects directory with the name MyProject and using the template template_blank_unreal, navigate to wvsProjects\\MyProjects run the following command: 

wvs project create --name "MyProject" --template "template_blank_unreal"

The command returns something like the following: 

C:\wvsProjects\MyProject>wvs project create --name "MyProject" --template "template_blank_unreal"
Cloning into '.'...
remote: Enumerating objects: 10, done.
remote: Total 10 (delta 0), reused 0 (delta 0), pack-reused 10
Receiving objects: 100% (10/10), done.
Checking objects: 100% (32/32), done.
Updating files: 100% (6/6), done.
add '.wvs/config.json'
[main 4b29b9e] Adding config.json file
 1 file changed, 5 insertions(+)
 create mode 100644 .wvs/config.json
Pushing to wvs.io:jackzhou/MyProject.git
Enumerating objects: 6, done.
Counting objects: 100% (6/6), done.
Delta compression using up to 12 threads
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 471 bytes | 471.00 KiB/s, done.
Total 4 (delta 1), reused 0 (delta 0), pack-reused 0
remote:
remote: ========================================================================
remote:
remote:      A <A HREF=" https://docs.wvs.io/wiki/downloads.html">new
remote:       release</a> of the WVS Desktop Client and the WVS CLI is now
remote:                                available!
remote:
remote: ========================================================================
remote:
To wvs.io:username/MyProject.git
   adf6e00..4b29b9e  main -> main
updating local tracking ref 'refs/remotes/origin/main'
OK

C:\wvsProjects\MyProject>dir

Import an external project

To learn more about importing a project into WVS, see Import Project.

Create a changelist

After your project is set up, you can start working on it by creating a changelist. A changelist is a list of files that you’ve made changes to in your cloned project that haven’t been committed to the project repository. These changes include creating files, deleting files, and changing existing files. WVS automatically detects your local changes and adds the changed files to the changelist.

To create a changelist, in your project directory, run the following command: 

wvs changelist begin --name "CHANGELIST_NAME"

Replace CHANGELIST_NAME with the name you want to give to the changelist.

Lock files

To lock files that you want to work on, run the following command: 

wvs changelist grab PATH/TO/FILE_1 PATH/TO/FILE_2 ...

You can lock as many files and directories as needed. After a file is locked, no one else can make changes to that file until you submit your changelist.

Submit your changelist

When you’re ready to send your changes back to the WVS repository, run the following command: 

wvs changelist finish

Next steps