# ----------------------------------------------------------------------------- # Copyright (c) Microsoft Corporation. All rights reserved. # Licensed under the MIT License. See License.txt in the project root for # license information. # ----------------------------------------------------------------------------- from knack.help_files import helps # pylint: disable=line-too-long, anomalous-backslash-in-string helps[''] = """ short-summary: Development utilities for Azure CLI 2.0. """ helps['setup'] = """ short-summary: Set up your environment for development of Azure CLI command modules and/or extensions. long-summary: Use --verbose to show the commands that are run, --debug to show the command output. examples: - name: Fully interactive setup. text: azdev setup - name: Install only the CLI in dev mode and search for the existing repo. text: azdev setup -c - name: Install public CLI and setup an extensions repo. Do not install any extensions. text: azdev setup -r azure-cli-extensions - name: Install CLI in dev mode, along with the extensions repo. Auto-find the CLI repo and install the `alias` extension in dev mode. text: azdev setup -c -r azure-cli-extensions -e alias - name: Install only the CLI in dev mode and resolve dependencies from setup.py. text: azdev setup -c -d setup.py """ helps['cli'] = """ short-summary: Commands for working with CLI modules. """ helps['cli check-versions'] = """ short-summary: Verify package versions against those hosted on PyPI. long-summary: > This is used to ensure the correct module versions are bumped prior to release. examples: - name: Verify all versions and audit them against PyPI. text: azdev cli check-versions """ helps['cli create'] = """ short-summary: Create a new Azure CLI module template. examples: - name: Scaffold a new CLI module named 'contoso'. text: azdev cli create contoso - name: Scaffold a new CLI module with the azure-mgmt-contoso SDK. text: > azdev cli create contoso --required-sdk azure-mgmt-contoso==0.1.0 --operation-name ContosoOperations --client-name ContosoManagementClient --sdk-property contoso_name """ helps['cli generate-docs'] = """ short-summary: > Generate reference docs for CLI commands. """ helps['configure'] = """ short-summary: Configure azdev for use without installing anything. """ helps['verify'] = """ short-summary: Verify CLI product features. """ helps['verify license'] = """ short-summary: Verify license headers. """ helps['verify document-map'] = """ short-summary: Verify documentation map. """ helps['verify default-modules'] = """ short-summary: Verify default modules. """ helps['verify package'] = """ short-summary: Verify the basic requirements for command module packages. """ helps['verify history'] = """ short-summary: Verify the README and HISTORY files for each module so they format correctly on PyPI. """ helps['style'] = """ short-summary: Check code style (pylint and PEP8). examples: - name: Check style for only those modules which have changed based on a git diff. text: azdev style --repo azure-cli --tgt upstream/master --src upstream/dev """ helps['test'] = """ short-summary: Record or replay CLI tests. parameters: - name: --pytest-args -a populator-commands: - pytest -h examples: - name: Run all tests. text: azdev test - name: Run tests for main modules. text: azdev test CLI - name: Run tests for extensions. text: azdev test EXT - name: Run tests for specific modules. text: azdev test {mod1} {mod2} - name: Run tests for specific cli modules, it is recommended to use the long name azure-cli-{mod}. text: azdev test azure-cli-vm azure-cli-compute - name: Run tests for specific extensions, it is recommended to use the long name azext_{ext}. text: azdev test azext_containerapp azext_aosm - name: Run tests for specific test files. text: azdev test test_account_scenario - name: Run tests for specific python class. text: azdev test SubscriptionClientScenarioTest - name: Run tests for specific test cases. text: azdev test test_account - name: Re-run the tests that failed the previous run. text: azdev test --lf - name: Run tests for a module but run the tests that failed last time first. text: azdev test {mod} -a --ff - name: Run tests for only those modules which have changed based on a git diff. text: azdev test --repo azure-cli --tgt upstream/master --src upstream/dev """ helps['linter'] = """ short-summary: Static code checks of the CLI command table. examples: - name: Check linter rules for only those modules which have changed based on a git diff. text: azdev linter --repo azure-cli --tgt upstream/master --src upstream/dev """ helps['scan'] = r""" short-summary: Scan secrets for files or string long-summary: Check built-in scanning rules at https://github.com/microsoft/security-utilities/blob/main/GeneratedRegexPatterns/PreciselyClassifiedSecurityKeys.json examples: - name: Scan secrets for a single file with custom patterns text: | azdev scan --file-path my_file.yaml --custom-pattern my_pattern.json ("my_pattern.json" contains the following content) { "Include": [ { "Pattern": "(?[\w.%#+-]+)(%40|@)([a-z0-9.-]*.[a-z]{2,})", "Name": "EmailAddress", "Signatures": ["%40", "@"] }, { "Pattern": "(?[0-9a-f]{8}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{4}-?[0-9a-f]{12})", "Name": "GUID" } ], "Exclude": [ { "Id": "SEC101/156", "Name": "AadClientAppIdentifiableCredentials", } ] } - name: Scan secrets for raw string and save results to file text: | azdev scan --data "my string waiting to be scanned" --save-scan-result True - name: Recursively scan secrets for a directory and save results to specific file text: | azdev scan --directory-path /path/to/my/folder --recursive --scan-result-path /path/to/scan_result.json - name: Scan secrets for all json files and yaml files within a directory text: | azdev scan --directory-path /path/to/my/folder --include-pattern *.yaml *.json """ helps['mask'] = """ short-summary: Mask secrets for files or string long-summary: | Redaction type 'FIXED_VALUE' will mask all secrets with '***'. Redaction type 'FIXED_LENGTH' will mask secrets with several '*'s which will keep the original secret length. Redaction type 'SECRET_NAME' redaction type will mask secrets with their secret name (type). Redaction type 'CUSTOM' will mask secrets with 'redaction_token' value you specify through saved scan result file. Check built-in scanning rules at https://github.com/microsoft/security-utilities/blob/main/GeneratedRegexPatterns/PreciselyClassifiedSecurityKeys.json """ helps['statistics'] = """ short-summary: Commands for CLI modules statistics. """ helps['statistics list-command-table'] = """ short-summary: List Command table for CLI module. examples: - name: List command table for the network module text: azdev statistics list-command-table network -o table - name: List command table for all modules of azure-cli repo, without commands details text: azdev statistics list-command-table CLI --statistics-only """ helps['statistics diff-command-tables'] = """ short-summary: Diff the command table change. examples: - name: Diff the command table change from May to Oct text: azdev statistics diff-command-tables --table-path command-table_May_01.json --diff-table-path command-table_Oct_01.json --statistics-only """ helps['command-change'] = """ short-summary: Commands for CLI modules meta data. """ helps['command-change meta-export'] = """ short-summary: Export Command meta data for CLI module. examples: - name: Export command meta for the monitor and network module text: azdev command-change meta-export network monitor -o table """ helps['command-change meta-diff'] = """ short-summary: Diff the command meta between provided meta files. examples: - name: Diff the command meta change from fileA to fileB text: azdev command-change meta-diff --base-meta-file fileA --diff-meta-file fileB --only-break """ helps['command-change tree-export'] = """ short-summary: Export Command Tree for CLI modules or extensions. examples: - name: Export command tree for CLI modules text: azdev command-change tree-export CLI --output-file command_tree.json """ helps['perf'] = """ short-summary: Commands to test CLI performance. """ helps['perf load-times'] = """ short-summary: Verify that all modules load within an acceptable timeframe. """ helps['perf benchmark'] = """ short-summary: Display benchmark staticstic of Azure CLI (Extensions) commands via execute it with "python -m azure.cli {COMMAND}" in a separate process. examples: - name: Run benchmark on "network application-gateway" and "storage account" text: azdev perf benchmark "network application-gateway -h" "storage account" "version" "group list" """ helps['extension'] = """ short-summary: Control which CLI extensions are visible in the development environment. """ helps['extension create'] = """ short-summary: Create a new Azure CLI extension template. examples: - name: Scaffold a new CLI extension named 'contoso'. text: azdev extension create contoso - name: Scaffold a new CLI extension with the azure-mgmt-contoso SDK. text: > azdev extension create contoso --local-sdk {sdkPath} --operation-name ContosoOperations --client-name ContosoManagementClient --sdk-property contoso_name """ helps['extension add'] = """ short-summary: Make an extension visible to the development environment. long-summary: The source code for the extension must already be on your machine. """ helps['extension build'] = """ short-summary: Construct a WHL file for one or more extensions. """ helps['extension remove'] = """ short-summary: Make an extension no longer visible to the development environment. long-summary: This does not remove the extensions source code from your machine. """ helps['extension list'] = """ short-summary: List what extensions are currently visible to your development environment. """ helps['extension show'] = """ short-summary: Show detailed extension info that installed in your development environment. """ helps['extension publish'] = """ short-summary: Build and publish an extension to a storage account. long-summary: Storage parameters may be persisted in the [defaults] section of your config file for convenience. examples: - name: Publish the contoso extension to a storage account and update the index. This will then be ready for a PR. text: > azdev extension publish contoso --update-index --storage-account mystorage --storage-account-key 0000-0000 --storage-container extensions """ helps['extension update-index'] = """ short-summary: Update the extensions index.json from a built WHL file. """ helps['extension cal-next-version'] = """ short-summary: Calculate valid version for next extension module release. """ helps['extension repo'] = """ short-summary: Commands to manage extension repositories for development. long-summary: > Extensions installed via the `az extension` commands are located in a specific folder. This folder is not well-suited for development. The CLI will look for in-development extensions in any number of Git repositories. These commands are used to add and remove repositories from the list of locations the CLI will search when looking for in-development extensions. """ helps['extension repo add'] = """ short-summary: Add an extension repository to search for in-development extensions. """ helps['extension repo remove'] = """ short-summary: > Remove a repository from the list of places to search for in-development extensions. long-summary: > This will not remove the extension repository from your system, but will appear to have the effect of uninstalling any extensions that were previously installed from that repository. """ helps['extension repo list'] = """ short-summary: > List the repositories that will be searched for in-development extensions. """ helps['extension generate-docs'] = """ short-summary: > Generate reference docs for CLI extensions commands. long-summary: > This command installs the extensions in a temporary directory and sets it as the extensions dir when generating reference docs. """ helps['cmdcov'] = """ short-summary: Run command test coverage and generate CLI command test coverage report. examples: - name: Check all CLI modules command test coverage. text: azdev cmdcov CLI - name: Check one or serveral modules command test coverage. text: azdev cmdcov vm storage - name: Check CLI modules command test coverage in argument level. text: azdev cmdcov CLI --level argument """ helps['generate-breaking-change-report'] = """ short-summary: Collect pre-announced breaking changes items and generate the report. examples: - name: Collect all pre-announced breaking changes, including any that did not specify a target version and group them by target version. text: azdev generate-breaking-change-report CLI --group-by-version --target-version None - name: Collect all pre-announced breaking changes target before next breaking change window, and display them in markdown. text: azdev generate-breaking-change-report CLI --output-format markdown - name: Collect all pre-announced breaking changes in vm, including those failed to specify a target version, and display them in json text: azdev generate-breaking-change-report vm --target-version None """