diff --git a/docs/Commands.md b/docs/Commands.md new file mode 100644 index 0000000..890a12d --- /dev/null +++ b/docs/Commands.md @@ -0,0 +1,136 @@ +# SK Azure Tools Commands + +The `sk-az-tools` package may act as a CLI tool that provides various commands for working with various services. Currently implemented commands support services related to: + +- Microsoft Entra ID +- Azure Resource Manager +- Azure DevOps Services + +## Login + +**Command name:** `login` + +**Usage:** `sk-az-tools login [--resources ] [--use-device-code] [--no-browser] [--browser ] [--browser-profile ] [global options]` + +**Options:** + +- `--resources` - Comma-separated resources to authenticate. Allowed values: `graph`, `devops`, `arm`. Default is all three. +- `--use-device-code` - Use device code flow instead of browser-based interactive flow. +- `--no-browser` - Do not launch browser automatically. Print the sign-in URL to stderr. +- `--browser` - Browser keyword used for interactive sign-in. Allowed values: `brave`, `browser`, `browserPrivate`, `chrome`, `edge`, `firefox`. +- `--browser-profile` - Chromium profile name (for example: `Default`, `Profile 1`). + +**Description:** The `login` command authenticates user sign-in for selected resource audiences and caches tokens for subsequent commands. + +## Logout + +**Command name:** `logout` + +**Usage:** `sk-az-tools logout [--all] [global options]` + +**Options:** + +- `--all` - Clear login state and remove all cached accounts. + +**Description:** The `logout` command signs out from cached user sessions. By default it signs out the active account; with `--all` it clears all cached accounts. + +## Get Token + +**Command name:** `get-token` + +**Usage:** `sk-az-tools get-token --type|-t [global options]` + +**Options:** + +- `--type`, `-t` - Token audience to retrieve. + +**Description:** The `get-token` command returns an access token for either Azure Resource Manager (`azurerm`) or Azure DevOps (`devops`) using the current login context. + +## REST + +**Command name:** `rest` + +**Usage:** `sk-az-tools rest [--method ] --url [--header ] [global options]` + +**Options:** + +- `--method` - HTTP method to use. Default: `GET`. +- `--url` - Full URL to call. +- `--header` - Extra request header to include (for example: `Content-Type: application/json`). + +**Description:** The `rest` command performs an HTTP request and returns response metadata and body. If `Authorization` is not provided explicitly, a `Bearer` token is added automatically for supported hosts: + +- `management.azure.com` - uses Azure Resource Manager token +- `dev.azure.com` - uses Azure DevOps token + +## List Apps + +**Command name:** `list-apps` + +**Usage:** `sk-az-tools list-apps [--display-name|-n ] [--app-id|-i ] [--filter|-f ] [global options]` + +**Options:** + +- `--display-name`, `-n` - Find applications by display name. +- `--app-id`, `-i` - Find application by application (client) ID. +- `--filter`, `-f` - Filter results by display name using glob pattern. + +**Description:** The `list-apps` command queries Microsoft Entra applications and returns matching app registrations. + +## List App Permissions + +**Command name:** `list-app-permissions` + +**Usage:** `sk-az-tools list-app-permissions --app-id|-i [--resolve|-r] [--short|-s] [--filter|-f ] [global options]` + +**Options:** + +- `--app-id`, `-i` - Application (client) ID. Required. +- `--resolve`, `-r` - Resolve permission GUIDs to human-readable names. +- `--short`, `-s` - Output compact result (omits permission GUID columns in output formatting step). +- `--filter`, `-f` - Filter permissions by name using glob pattern. + +**Description:** The `list-app-permissions` command returns required API permissions declared by the target app registration. + +## List App Grants + +**Command name:** `list-app-grants` + +**Usage:** `sk-az-tools list-app-grants --app-id|-i [global options]` + +**Options:** + +- `--app-id`, `-i` - Application (client) ID. Required. + +**Description:** The `list-app-grants` command lists OAuth2 delegated permission grants associated with the specified app. + +## List Resource Permissions + +**Command name:** `list-resource-permissions` + +**Usage:** `sk-az-tools list-resource-permissions [--app-id|-i | --display-name|-n ] [--filter|-f ] [global options]` + +**Options:** + +- `--app-id`, `-i` - Resource application ID. +- `--display-name`, `-n` - Resource application display name. +- `--filter`, `-f` - Filter permissions by name using glob pattern. + +**Description:** The `list-resource-permissions` command returns available delegated and application permissions exposed by a resource app. + +## Table + +**Command name:** `table` + +**Usage:** `sk-az-tools table [--header|-H ] [global options]` + +**Options:** + +- `--header`, `-H` - Header definition. Possible values: + - `col1, col2, ...` - Column names separated by comma. The number of columns must match the number of columns in the table. + - `key1: Col1, key2: Col2, ...` - property names followed by column and the column name. The number of pairs must match the number of columns in the table. + - `auto`, `a` - header is generated automatically based on the first row of the table + - `original`, `o` - header is generated based on the original table (before any transformations) + +**Description:** The `table` command act as a filter that transforms JSON input into a Markdown table. It uses built-in Markdown table formatter, but on arbitrary JSON input. +