Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

DOCS-3106: Document CLI usability improvements #3960

Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

DOCS-3106: Document CLI usability improvements #3960

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
979c429
DOCS-3106: Document CLI usability improvements
JessamyT Feb 1, 2025
14569fe
Fix order on page
JessamyT Feb 1, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
94 changes: 74 additions & 20 deletions docs/dev/tools/cli.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -598,7 +598,7 @@ See [Authenticate](#authenticate).
| -------------- | ----------- | -------------------- |
| `api-key` | Authenticate to Viam using an organization, location, or machine part API key. | - |
| `print-access-token` | Prints the access token used to authenticate the current CLI session. | - |
| `--disable-browser-open` | Authenticate in a headless environment by preventing the opening of the default browser during login (default: `false`). | - |
| `--no-browser` | Authenticate in a headless environment by preventing the opening of the default browser during login (default: `false`). | - |
| `--help` | Return help. | - |

##### Named arguments
Expand Down Expand Up @@ -1091,7 +1091,7 @@ See [create an organization API key](#create-an-organization-api-key) for more i
<!-- prettier-ignore -->
| Command option | Description | Positional arguments |
| -------------- | ----------- | -------------------- |
| `list` | List all organizations (name, id, and [namespace](/operate/reference/naming-modules/#create-a-namespace-for-your-organization)) that the authenticated session has access to. | - |
| `list` | List all organizations (name, ID, and [namespace](/operate/reference/naming-modules/#create-a-namespace-for-your-organization)) that the authenticated session has access to. | - |
| `api-key create` | Create a new organization API key. | - |
| `support-email get` | Get the support email for an organization. | - |
| `support-email set` | Set the support email for an organization. | - |
Expand Down Expand Up @@ -1159,6 +1159,59 @@ viam packages export --org-id=123 --name=MyMLModel --version=latest --type=ml_mo
| `--path` | The path to the package for upload. The package should be zipped with tar and have the `.tar.gz` extension. | `upload` | **Required** |
| `--destination` | The output directory for downloaded package. | `export` | **Required** |

### `profiles`

The `profiles` command allows you to manage different CLI authentication profiles, so you can easily switch between API key authentications (for example authentication to one organization versus another).

```sh {class="command-line" data-prompt="$"}
viam profiles add --profile-name=<name-of-profile-to-add> --key-id=<API-key-ID> --key=<API-key>
viam profiles update --profile-name=<name-of-profile-to-update> --key-id=<API-key-ID> --key=<API-key>
viam profiles list
viam profiles remove --profile-name=<name-of-profile-to-remove>
```

Examples:
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

These examples are great for showing how to create and store profiles, but don't highlight how to actually use these profiles. Might be useful to have an example of something like viam --profile=<name-of-profile-to-use> machines list?


```sh {id="terminal-prompt" class="command-line" data-prompt="$"}
# Add a new profile for authentication (throws error if profile already exists)
viam profiles add --profile-name=mycompany --key-id=54321zyx --key=123abcd1234

# Update an existing profile for authentication, or add it if it doesn't exist
viam profiles update --key=123abcd1234 --key-id=54321zyx --profile-name=mycompany

# List all existing profiles by name
viam profiles list

# Remove a profile
viam profiles remove --profile-name=mycompany
```

See [create an organization API key](#create-an-organization-api-key) for more information.

{{% alert title="Tip" color="tip" %}}
You can set a default profile by using the `VIAM_CLI_PROFILE_NAME` environment variable.
{{% /alert %}}

#### Command options

<!-- prettier-ignore -->
| Command option | Description | Positional arguments |
| -------------- | ----------- | -------------------- |
| `add` | List all existing profiles by name. | - |
| `update` | Update an existing profile for authentication, or add it if it doesn't exist. | - |
| `list` | List all existing profiles by name. | - |
| `remove` | Remove a profile. | - |
| `--help` | Return help | - |

##### Named arguments

<!-- prettier-ignore -->
| Argument | Description | Applicable commands | Required? |
| -------- | ----------- | ------------------- | --------- |
| `--profile-name` | Name of the profile to add, update, or remove. | `add`, `update`, `remove` | **Required** |
| `--key-id` | The `key id` (UUID) of the API key. | `add`, `update` | **Required** |
| `--key` | The `key value` of the API key. | `api-key`, `update` | **Required** |

### `machines` (alias `robots`)

The `machines` command allows you to manage your machine fleet.
Expand All @@ -1179,7 +1232,7 @@ viam machines api-key create --machine-id=<machine-id> [...named args]
viam machines part logs --machine=<machine> --part=<part> [...named args]
viam machines part status --organization=<org name> --location=<location name> --machine=<machine id>
viam machines part run --organization=<org name> --location=<location name> --machine=<machine id> [--stream] --data <meth>
viam machines part shell --organization=<org name> --location=<location name> --machine=<machine id>
viam machines part shell --organization=<org name> --location=<location name> --machine=<machine id> --part=<part id>
viam machines part restart --machine=<machine id> --part=<part id>
viam machines part cp --organization=<org name> --location=<location name> --machine=<machine id> --part=<part name> <file name> machine:/path/to/file
```
Expand All @@ -1191,45 +1244,42 @@ Examples:
viam machines list

# get machine status
viam machines status --machine=123 --organization="Robot's Org" --location=myLoc
viam machines status --machine=123 --location=myLoc
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm a little unclear about why we don't include organization anymore here, but we include it immediately above? Is the goal for one to be all flags and the other to be only mandatory flags? If so, we can probably get rid of location here as well.


# create an api key for a machine
viam machines api-key create --machine-id=123 --name=MyKey

# stream logs from a machine
viam machines logs --machine=123 \
--organization="Robot's Org" --location=myLoc
viam machines logs --machine=123

# stream logs from a machine part
viam machines part logs --machine=123 \
--organization="Robot's Org" --location=myLoc --part=myrover-main --tail=true
viam machines part logs --part=myrover-main --tail=true

# stream classifications from a machine part every 500 milliseconds from the Viam Vision Service with classifier "stuff_detector"
viam machines part run --machine=123 \
--organization="Robot's Org" --location=myLoc --part=myrover-main --stream=500ms \
viam machines part run --part=myrover-main --stream=500ms \
--data='{"name": "vision", "camera_name": "cam", "classifier_name": "stuff_classifier", "n":1}' \
viam.service.vision.v1.VisionService.GetClassificationsFromCamera

# restart a part of a specified machine
viam machines part restart --machine=123 --part=456
viam machines part restart --part=123

# Copy and a single file to a machine and change the file's name:
viam machine part cp --organization=my_org --location=my_location --machine=my_machine --part=m1-main my_file machine:/home/user/
viam machine part cp --part=m1-main my_file machine:/home/user/

# Recursively copy a directory to a machine:
viam machine part cp --machine=123 --part=123 -r my_dir machine:/home/user/
viam machine part cp --part=123 -r my_dir machine:/home/user/

# Copy multiple files to a machine with recursion and keep original permissions and metadata for the files:
viam machine part cp --machine=123 --part=123 -r -p my_dir my_file machine:/home/user/some/existing/dir/
viam machine part cp --part=123 -r -p my_dir my_file machine:/home/user/some/existing/dir/

# Copy a single file from a machine to a local destination:
viam machine part cp --machine=123 --part=123 machine:my_file ~/Downloads/
viam machine part cp --part=123 machine:my_file ~/Downloads/

# Recursively copy a directory from a machine to a local destination:
viam machine part cp --machine=123 --part=123 -r machine:my_dir ~/Downloads/
viam machine part cp --part=123 -r machine:my_dir ~/Downloads/

# Copy multiple files from the machine to a local destination with recursion and keep original permissions and metadata for the files:
viam machine part cp --machine=123 --part=123 -r -p machine:my_dir machine:my_file ~/some/existing/dir/
viam machine part cp --part=123 -r -p machine:my_dir machine:my_file ~/some/existing/dir/
```

#### Command options
Expand Down Expand Up @@ -1270,8 +1320,8 @@ viam machine part cp --machine=123 --part=123 -r -p machine:my_dir machine:my_fi
<!-- prettier-ignore -->
| Argument | Description | Applicable commands | Required? |
| -------- | ----------- | ------------------- | --------- |
| `--organization` | Organization name or ID that the machine belongs to | `list`, `status`, `logs`, `part` | **Required** |
| `--location` | Location name or ID that the machine belongs to or to list machines in | `list`, `status`, `logs`, `part` | **Required** |
| `--organization` | Organization name or ID that the machine belongs to | `list`, `status`, `logs`, `part` | Optional |
| `--location` | Location name or ID that the machine belongs to or to list machines in | `list`, `status`, `logs`, `part` | Optional |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure what command this all is so I may be wrong, but machine below is still listed as Required but we also have part as a flag. I think if part is useful information then machine becomes optional (because machine can often be inferred from part, provided it's given as a part-id).

| `--machine` | Machine name or ID for which the command is being issued. If machine name is used instead of ID, `--organization` and `--location` are required. | `status`, `logs`, `part` | **Required** |
| `--errors` | Boolean, return only errors (default: false) | `logs` | Optional |
| `--levels` | Filter logs by levels (debug, info, warn, error). Accepts multiple inputs in comma-separated list. | `logs` | Optional |
Expand Down Expand Up @@ -1470,4 +1520,8 @@ You can pass global options after the `viam` CLI keyword with any command.
<!-- prettier-ignore -->
| Global option | Description |
| ------------- | ----------- |
| `--debug` | Enable debug logging (default: false) |
| `--debug` | Enable debug logging (default: false). |
| `--disable-profiles`, `disable-profile` | Disable usage of [profiles](#profiles), falling back to default (false) behavior. |
| `--help`, `-h` | Show help (default: false). |
| `--profile` | Specify a particular [profile](#profiles) for the current command. |
| `--quiet`, `-q` | Suppress warnings (default: false). |
Loading