diff --git a/docs/dev/tools/cli.md b/docs/dev/tools/cli.md index a20cabbf01..16126ce147 100644 --- a/docs/dev/tools/cli.md +++ b/docs/dev/tools/cli.md @@ -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 ``` @@ -563,7 +563,7 @@ viam locations api-key create --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` @@ -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 @@ -1096,7 +1096,7 @@ See [create an organization API key](#create-an-organization-api-key) for more i | 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. | - | @@ -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= --key-id= --key= +viam profiles update --profile-name= --key-id= --key= +viam profiles list +viam profiles remove --profile-name= +``` + +Examples: + +```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 + + +| 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 + + +| 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. @@ -1179,15 +1235,15 @@ This includes: ```sh {class="command-line" data-prompt="$"} viam machines list -viam machines status --organization= --location= --machine= -viam machines logs --organization= --location= --machine= [...named args] -viam machines api-key create --machine-id= [...named args] -viam machines part logs --machine= --part= [...named args] -viam machines part status --organization= --location= --machine= -viam machines part run --organization= --location= --machine= [--stream] --data -viam machines part shell --organization= --location= --machine= +viam machines status --org= --location= --machine= +viam machines logs --org= --location= --machine= [...named args] +viam machines api-key create --machine= [...named args] +viam machines part logs --machine= --part= [...named args] +viam machines part status --org= --location= --machine= +viam machines part run --org= --location= --machine= [--stream] --data +viam machines part shell --org= --location= --machine= --part= viam machines part restart --machine= --part= -viam machines part cp --organization= --location= --machine= --part= machine:/path/to/file +viam machines part cp --org= --location= --machine= --part= machine:/path/to/file ``` Examples: @@ -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 @@ -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. | @@ -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. | @@ -1280,27 +1333,26 @@ viam machine part cp --machine=123 --part=123 -r -p machine:my_dir machine:my_fi | 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 @@ -1482,4 +1534,8 @@ You can pass global options after the `viam` CLI keyword with any command. | 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). |