Skip to content

DOCS-3106: Document CLI usability improvements #3960

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.

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

Merged
merged 5 commits into from
Feb 15, 2025
Merged
Changes from all commits
Commits
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
140 changes: 98 additions & 42 deletions docs/dev/tools/cli.md
Original file line number Diff line number Diff line change
Expand Up @@ -26,7 +26,7 @@ The CLI lets you:
For example, this CLI command moves a servo to the 75 degree position:

```sh {class="command-line" data-prompt="$"}
viam machines part run --machine 82c608a-1be9-46a5 --organization "Artoo's Org" \
viam machines part run --machine 82c608a-1be9-46a5 --org "Artoo's Org" \
--location myLoc --part "mymachine-main" --data '{"name": "myServo", "angle_deg":75}' \
viam.component.servo.v1.ServoService.MoveRequest
```
Expand Down Expand Up @@ -563,7 +563,7 @@ viam locations api-key create --location-id=<location-id>
| Command option | Description | Positional arguments |
| -------------- | ----------- | -------------------- |
| `list` | List all locations (name and id) that the authenticated session has access to, grouped by organization | **organization id** : (_optional_) return results for specified organization only |
| `api-key` | Work with an api-key for your location | `create` |
| `api-key` | Work with an API key for your location | `create` |
| `--help` | Return help | - |

##### Positional arguments: `api-key`
Expand Down Expand Up @@ -603,7 +603,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 @@ -1096,7 +1096,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 @@ -1165,6 +1165,62 @@ 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?

Copy link
Collaborator Author

Choose a reason for hiding this comment

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

Good call--adding!


```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

# Example of using a profile to see a list of machines available to that profile
viam --profile=mycompany machines list
```

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,15 +1235,15 @@ This includes:

```sh {class="command-line" data-prompt="$"}
viam machines list
viam machines status --organization=<org name> --location=<location name> --machine=<machine id>
viam machines logs --organization=<org name> --location=<location name> --machine=<machine id> [...named args]
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 status --org=<org id> --location=<location id> --machine=<machine id>
viam machines logs --org=<org id> --location=<location id> --machine=<machine id> [...named args]
viam machines api-key create --machine=<machine id> [...named args]
viam machines part logs --machine=<machine id> --part=<part id> [...named args]
viam machines part status --org=<org id> --location=<location id> --machine=<machine id>
viam machines part run --org=<org id> --location=<location id> --machine=<machine id> [--stream] --data <meth>
viam machines part shell --org=<org id> --location=<location id> --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
viam machines part cp --org=<org id> --location=<location id> --machine=<machine id> --part=<part id> <file name> machine:/path/to/file
```

Examples:
Expand All @@ -1197,48 +1253,45 @@ Examples:
viam machines list

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

# create an api key for a machine
viam machines api-key create --machine-id=123 --name=MyKey
viam machines api-key create --machine=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

# tunnel connections to the specified port on a machine part
viam machine part tunnel --part=123 --destination-port=1111 --local-port 2222

# 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=123 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 All @@ -1247,7 +1300,7 @@ viam machine part cp --machine=123 --part=123 -r -p machine:my_dir machine:my_fi
| Command option | Description | Positional arguments |
| -------------- | ----------- | -------------------- |
| `list` | List all machines that the authenticated session has access to, filtered by organization and location. | - |
| `api-key` | Work with an api-key for your machine | `create` (see [positional arguments: api-key](#positional-arguments-api-key)) |
| `api-key` | Work with an API key for your machine | `create` (see [positional arguments: api-key](#positional-arguments-api-key)) |
| `status` | Retrieve machine status for a specified machine | - |
| `logs` | Retrieve logs for a specified machine | - |
| `part` | Manage a specified machine part | `status`, `run`, `logs`, `shell`, `restart`, `tunnel`, `cp` (see [positional arguments: part](#positional-arguments-part)). To use the `part shell` and `part cp` commands, you must add the [ViamShellDanger fragment](https://app.viam.com/fragment/b511adfa-80ab-4a70-9bd5-fbb14696b17e/json) to your machine. |
Expand All @@ -1268,7 +1321,7 @@ viam machine part cp --machine=123 --part=123 -r -p machine:my_dir machine:my_fi
| -------- | ----------- |
| `status` | Retrieve machine status for a specified machine part |
| `run` | Run a component or service command, optionally at a specified interval. For commands that return data in their response, you can use this to stream data. |
| `logs` | Get logs for the specified machine part |
| `logs` | Get logs for the specified machine or machine part |
| `shell` | Access a machine part securely using a secure shell. To use this feature you must add the [`ViamShellDanger` fragment](https://app.viam.com/fragment/b511adfa-80ab-4a70-9bd5-fbb14696b17e/json) to your machine. |
| `restart` | Restart a machine part. |
| `cp` | Copy files to and from a machine part. |
Expand All @@ -1280,27 +1333,26 @@ 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** |
| `--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 |
| `--part` | Part ID for which the command is being issued. | `part` | **Required** |
| `--machine` | Machine ID for which the command is being issued. If machine name is used instead of ID, `--org` and `--location` are required. | `status`, `logs` | **Required** |
| `--location` | ID of the location that the machine belongs to or to list machines in. | `list`, `status`, `logs`, `part` | Optional |
| `--org` | ID of the organization that the machine belongs to or to list machines in. | `list`, `status`, `logs`, `part` | Optional |
| `--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 |
| `--part` | Part name or ID for which the command is being issued | `logs`, `part` | Optional |
| `--tail` | Tail (stream) logs, boolean(default false) | `part logs` | Optional |
| `--tail` | Tail (stream) logs, boolean(default false). | `part logs` | Optional |
| `--keyword` | Filter logs by keyword. | `logs` | Optional |
| `--start` | Filter logs to include only those after the start time. Time format example: `2025-01-13T21:30:00Z` (ISO-8601 timestamp in RFC3339). | `logs` | Optional |
| `--end` | Filter logs to include only those before the end time. Time format example: `2025-01-13T21:35:00Z` (ISO-8601 timestamp in RFC3339). | `logs` | Optional |
| `--count` | The number of logs to fetch. | `logs` | Optional |
| `--format` | THe file format for the output file. Options: `text` or `json`. | `logs` | Optional |
| `--output` | The path to the output file to store logs in. | `logs` | Optional |
| `--stream` | If specified, the interval in which to stream the specified data, for example, 100ms or 1s | `part run` | Optional |
| `--data` | Command data for the command being request to run (see [data argument](#using-the---stream-and---data-arguments)) | `part run` | **Required** |
| `--machine-id` | The machine to create an API key for | `api-key` | **Required** |
| `--name` | The optional name of the API key | `api-key` | Optional |
| `--org-id` | The optional organization ID to attach the key to | `api-key` | Optional |
| `--stream` | If specified, the interval in which to stream the specified data, for example, 100ms or 1s. | `part run` | Optional |
| `--data` | Command data for the command being request to run (see [data argument](#using-the---stream-and---data-arguments)). | `part run` | **Required** |
| `--machine-id` | The machine to create an API key for. | `api-key` | **Required** |
| `--name` | The optional name of the API key. | `api-key` | Optional |
| `--recursive`, `-r` | Recursively copy files. Default: `false`. | `part cp` | Optional |
| `--preserve`, `-p` | Preserve modification times and file mode bits from the source files. Default: `false`. | `part cp` | Optional |
| `--desination-port` | The port on a machine part to tunnel to. | `part tunnel` | **Required** |
| `--destination-port` | The port on a machine part to tunnel to. | `part tunnel` | **Required** |
| `--local-port` | The local port from which to tunnel. | `part tunnel` | **Required** |

##### Using the `--stream` and `--data` arguments
Expand Down Expand Up @@ -1482,4 +1534,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