# Getting started with hv

This section covers the essentials you need to start using hv command-line tool: setting up authentication and understanding vault path formats.

## hv credentials

In order to connect to the vault server, hv must at least have:

* a username
* a password
* a hostname

For example:

```
$ hv -hhexvault.acme.com:65433 -uadmin -psecret users
LastActive Adm    Login        Email
---------- --- ------------ ------------
2022-06-27  *  admin
2022-06-22     alice       Alice <alice@acme.com>
Never          bob         Bob <bob@acme.com>
...
```

There are 3 ways to specify credentials (in decreasing order of priority):

* providing them as command-line arguments (as in the example above)
* storing them in [environment variables](#environment-variables)
* storing them in [the registry+keychain](#registry--keychain) (recommended)

All credentials, including usernames, are case-senstive, meaning that "Joe" and "joe" would be different users.

### Command line

Passing credentials on the command line will always take precedence over [environment variables](#environment-variables) and [registry+keychain](#registry--keychain).

|              |                                                                                                                                                                             |
| ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `-uUSERNAME` | specify username                                                                                                                                                            |
| `-pPASSWORD` | specify password                                                                                                                                                            |
| `-hHOST`     | specify host (server:port) (if port is omitted, defaults to 65433)                                                                                                          |
| `-sSITENAME` | specify site                                                                                                                                                                |
| `--set`      | remember credentials. This option doesn’t require the credentials to be passed through the command line, credentials passed through environment variables will work as well |

### Environment variables

Credentials can also be passed through environment variables. They will take precedence over those possibly found in the [registry+keychain](#registry--keychain).

|              |                                                        |
| ------------ | ------------------------------------------------------ |
| `VAULT_HOST` | the server host name                                   |
| `VAULT_PORT` | the server port                                        |
| `VAULT_USER` | the username to connect to the server                  |
| `VAULT_PASS` | the user’s password                                    |
| `VAULT_SITE` | the site to use (most commands need a site to operate) |

### Registry + keychain

Unless environment variables or command-line arguments are provided, `hv` will look for credentials in [the registry](https://docs.hex-rays.com/user-guide/concepts/site#the-registry) (and [the OS’s keychain](https://github.com/HexRaysSA/docs/blob/9.3/user-guide/teams/users-permissions.md##passwords-storage-in-the-oss-keychain) for passwords.)

Credentials can be stored in the registry (and keychain) like so:

```
alice@alice_PC$ hv --set -ualice -palice -hvaultserver -salice_on_alicepc
```

The user, host (and optional site) will be persisted in [the registry](https://docs.hex-rays.com/user-guide/concepts/site#the-registry), while the password will be saved to [the OS’s keychain](https://github.com/HexRaysSA/docs/blob/9.3/user-guide/teams/users-permissions.md#passwords-storage-in-the-oss-keychain).

For this operation to succeed, at least a user and host must be provided

In order to keep the various commands' syntax as clear as possible, we will assume that the user has stored credentials (in either the [registry+keychain](#registry--keychain) or [environment variables](#environment-variables)) for the rest of this manual.

### Best practices

We recommend persisting credentials using [the registry+keychain method](#registry--keychain).

Once that is done, commands will become cleaner:

```
>./hv info

Hex-Rays Vault Server v1
Vault time: 2022-04-14 15:36:29, up since 2022-04-14 15:17:25
...
```

if you login to the server using `hvui` and save the login information, it will end up in the [the registry+keychain method](#registry--keychain), and thus `hv` will then be able to use that information as well.

## Path formats

**Local paths** refer to a file on the host file system.

**Vault paths** refer to a file mapped on the vault. They can start with `//` to refer to the root of the vault.

Some vault paths can optionally specify the revision of the path.

Special symbols were created to access specific revisions:

|     |                                              |
| --- | -------------------------------------------- |
| `^` | last revision available on the vault         |
| `=` | current revision, that is synced on the site |
| `*` | all revisions                                |

Special file revision symbols

|            |                                                         |
| ---------- | ------------------------------------------------------- |
| `subdir/`  | means all files in all subdirectories                   |
| `subdir`   | means all files in all subdirectories (same as subdir/) |
| `subdir/*` | means all files in the directory                        |

Directories and wildcards

### Examples

Get the first revision of a file:

```
$ hv sync //malware/Ransomware.WannaCry/41aa.exe.i64#1
ok synced //malware/Ransomware.WannaCry/41aa.exe.i64#1 (838724 bytes)
ok sync completed
```

Sync to the last version of a file:

```
$ hv sync malware/Ransomware.WannaCry/41aa.exe.i64#^
ok synced //malware/Ransomware.WannaCry/41aa.exe.i64#3 (846916 bytes)
ok sync completed
```

Force sync to the current revision (we must specify -f to force a file transfer):

```
$ hv sync -f malware/Ransomware.WannaCry/41aa.exe.i64#=
ok synced //malware/Ransomware.WannaCry/41aa.exe.i64#2 (846916 bytes)
ok sync completed
```

Display md5 checksums of all revisions of a file:

```
$ hv md5 malware/Ransomware.WannaCry/41aa.exe.i64#*
ok 8F464140FA3DA4A20B03166F2E80325B //malware/Ransomware.WannaCry/41aa.exe.i64#1
ok E0F7B984151FEF497985F375C64FA5C7 //malware/Ransomware.WannaCry/41aa.exe.i64#2
ok 5C3B88306CF0D93DC35FFD67A710AE3B //malware/Ransomware.WannaCry/41aa.exe.i64#3
```

List Hex-Rays Vault server’s toplevel directory contents:

```
$ hv dir //
2022-06-02 10:29:30       140267 CL29/edit //malware/cppobj_virtcall.i64#9
2022-06-14 16:44:19      2173541 CL36/edit //iOS/dyld_ios16.i64#3
```

Plan to add a file to the vault:

```
$ hv add /path/to/local_rootdir/enable.png
ok added '//enabled.png'
```

Plan to add a directory:

```
$ hv add /path/to/local_rootdir/REsearch
ok added '//REsearch/vm2vm.dat'
ok added '//REsearch/vm2vm.exe'
ok added '//REsearch/vm2vm.i64'
```

Plan to delete a file:

```
$ hv del /path/to/local_rootdir/REsearch/*.dat
ok checked out '//REsearch/vm2vm.dat' for 'del' (worklist 1)
```

Show worklist to which files were added:

```
$ hv worklist show
WL 1 add  //REsearch/vm2vm.exe#0
WL 1 add  //REsearch/vm2vm.i64#0
WL 1 edit //cppobj_virtcall.i64#9
WL 1 add  //enabled.png#0
```

It is safe to interrupt a command using Ctrl-C. The file transfers in action will be gracefully terminated, so that no partially received files will be left on the disk. However, the requests that were delivered to the server will still be carried out up to the completion. For example, if the user asked to check out thousands of files for editing, this will be performed even if the user presses Ctrl-C after invoking the command.

If the command syntax specifies ellipsis (…​), it means that multiple path patterns can be specified. The path patterns can be specified using local paths or vault paths, which start with a double slash (`//`).