feat!: 2.0 CLI grammar normalization — positional NAME, universal containers, flag unification (#248)

.changeset/0010-v2-grammar.md

@@ -0,0 +1,5 @@
+---
+"pan-scm-cli": major
+---
+
+**2.0: one CLI grammar, everywhere (breaking).** Object names are now positional (`scm set object tag prod --color Red`, not `--name prod`). Every containerized set/delete/show accepts `--folder`, `--snippet`, and `--device` with exactly-one enforcement (previously ~20 types were folder-only). All `load` commands support `--dry-run`; all `backup` commands support `--file` (including SASE). Flag unification: tags are always `--tags` (repeatable) — CSV `--tag` variants removed; `vlan-interface --tag` renamed `--vlan-id`; job ids are always `--id` (operations `--job-id` removed); dead `--list` flags removed from identity shows; dead `--mock` params removed from insights (use `SCM_MOCK=1`). Show commands gained `--max-results`. There are no deprecation aliases — update scripts to the new grammar (see the migration table in the release notes).

README.md

@@ -33,7 +33,7 @@ scm context create myenv \
 scm show object address --folder Texas
 
 # create an address
-scm set object address --folder Texas --name webserver --ip-netmask 10.1.1.100/32
+scm set object address webserver --folder Texas --ip-netmask 10.1.1.100/32
 
 # backup to YAML
 scm backup object address --folder Texas

docs-site/docs/about/getting-started.md

@@ -88,15 +88,16 @@ variables for secure credential management. Regularly rotate your credentials.
 All commands follow this pattern:
 
 ```bash
-scm <action> <category> <resource> [options]
+scm <action> <category> <resource> [name] [options]
 ```
 
 | Component | Description | Examples |
 | --- | --- | --- |
-| `<action>` | Operation to perform | `set`, `delete`, `load`, `show`, `backup` |
+| `<action>` | Operation to perform | `set`, `delete`, `load`, `show`, `backup`, `move` |
 | `<category>` | Category of resource | `object`, `network`, `security`, `sase` |
-| `<resource>` | Specific resource type | `address`, `address-group`, `security-zone` |
-| `[options]` | Resource-specific parameters | `--folder`, `--name`, `--ip-netmask` |
+| `<resource>` | Specific resource type | `address`, `address-group`, `zone` |
+| `[name]` | Positional resource name (required for `set`/`delete`/`move`; optional for `show`) | `webserver` |
+| `[options]` | Resource-specific parameters | `--folder`, `--ip-netmask` |
 
 ## Basic Usage Examples
 
@@ -115,39 +116,51 @@ Options:
   --help     Show this message and exit.
 
 Commands:
-  backup   Backup configurations to YAML files
-  delete   Remove configurations
-  load     Load configurations from YAML files
-  set      Create or update configurations
-  show     Display configurations
+  backup      Backup configurations to YAML files
+  commit      Commit staged configuration changes
+  context     Manage authentication contexts
+  delete      Remove configurations
+  incidents   Search and view security incidents
+  insights    Query monitoring insights
+  jobs        Manage SCM jobs
+  load        Load configurations from YAML files
+  local       Retrieve local device configurations
+  move        Move rules to a new position
+  operations  Run device operations
+  posture     Firewall posture / BPA assessment
+  set         Create or update configurations
+  show        Display configurations
 ```
 
 Command-specific help:
 
 ```bash
 $ scm set object address --help
-Usage: scm set object address [OPTIONS]
+Usage: scm set object address [OPTIONS] NAME
 
-  Create or update an address object in SCM.
+  Create or update an address object.
+
+Arguments:
+  NAME                     Name of the address  [required]
 
 Options:
-  --folder TEXT            Folder for the address object  [required]
-  --name TEXT              Name of the address object  [required]
-  --description TEXT       Description for the address
-  --tags LIST              List of tags to apply to the address
-  --ip-netmask TEXT        Address in CIDR notation (e.g., 192.168.1.0/24)
-  --ip-range TEXT          Address range (e.g., 192.168.1.1-192.168.1.10)
-  --ip-wildcard TEXT       Address with wildcard mask (e.g., 10.20.1.0/0.0.248.255)
-  --fqdn TEXT              Fully qualified domain name (e.g., example.com)
+  --folder TEXT            Folder location
+  --snippet TEXT           Snippet location
+  --device TEXT            Device location
+  --description TEXT       Description of the address
+  --tags TEXT              Tags (repeat for multiple)
+  --ip-netmask TEXT        IP address with CIDR notation (e.g. 192.168.1.0/24)
+  --ip-range TEXT          IP address range (e.g. 192.168.1.1-192.168.1.10)
+  --ip-wildcard TEXT       IP wildcard mask (e.g. 10.20.1.0/0.0.248.255)
+  --fqdn TEXT              Fully qualified domain name (e.g. example.com)
   --help                   Show this message and exit.
 ```
 
 ### Creating an Address Object
 
 ```bash
-$ scm set object address \
+$ scm set object address webserver \
     --folder Texas \
-    --name webserver \
     --ip-netmask 192.168.1.100/32 \
     --description "Web server"
 ---> 100%
@@ -157,9 +170,8 @@ Created address: webserver in folder Texas
 ### Creating an Address with FQDN
 
 ```bash
-$ scm set object address \
+$ scm set object address company-website \
     --folder Texas \
-    --name company-website \
     --fqdn example.com \
     --description "Company website"
 ---> 100%
@@ -186,7 +198,7 @@ Name: company-website
 ### Deleting an Address Object
 
 ```bash
-$ scm delete object address --folder Texas --name webserver
+$ scm delete object address webserver --folder Texas
 ---> 100%
 Deleted address: webserver from folder Texas
 ```
@@ -241,30 +253,27 @@ Successfully loaded 3 out of 3 addresses from 'addresses.yml'
 
 ### Dry Run Mode
 
-Preview changes without applying them:
+Preview bulk changes without applying them (available on every `load` command):
 
 ```bash
-$ scm set object address \
-    --folder Texas \
-    --name webserver \
-    --ip-netmask 192.168.1.100/32 \
-    --dry-run
+$ scm load object address --file addresses.yml --dry-run
 ---> 100%
-[DRY RUN] Would create address: webserver in folder Texas
+Dry run mode: would apply the following configurations:
+- name: web-server-1
+  folder: Texas
+  ip_netmask: 192.168.1.10/32
 ```
 
 ### Mock Mode
 
-Run commands without connecting to the SCM API:
+Set `SCM_MOCK=1` to run commands without connecting to the SCM API:
 
 ```bash
-$ scm set object address \
+$ SCM_MOCK=1 scm set object address webserver \
     --folder Texas \
-    --name webserver \
-    --ip-netmask 192.168.1.100/32 \
-    --mock
+    --ip-netmask 192.168.1.100/32
 ---> 100%
-[MOCK] Created address: webserver in folder Texas
+Created address: webserver in folder Texas
 ```
 
 :::tip

docs-site/docs/about/release-notes.md

@@ -2,6 +2,29 @@
 
 This page contains the release history of the Strata Cloud Manager CLI, with the most recent releases at the top.
 
+## Version 2.0.0
+
+**Released:** July 2026
+
+### Changed (BREAKING)
+
+- **Positional NAME argument**: `set`, `delete`, `show`, and `move` commands now take the resource name as a positional argument instead of `--name`.
+    - Old: `scm set object address --folder Texas --name web1 --ip-netmask 10.0.0.1/32`
+    - New: `scm set object address web1 --folder Texas --ip-netmask 10.0.0.1/32`
+    - `show` without a name lists all items.
+    - Exceptions: quarantined devices use `--host-id`; network locations use `--value`; `bgp-routing` and mobile-agent `global-setting` are singletons with no name.
+    - **Migration**: Move the `--name` value to the position immediately after the object type.
+- **Containers everywhere**: `set`/`delete`/`show` for object, network, security, and identity types accept exactly one of `--folder`, `--snippet`, or `--device`. SASE resources and setup folder/label/snippet/device remain container-less; mobile-agent commands remain folder-only (SDK limitation).
+- **Repeatable `--tags`**: Tags are always provided by repeating the flag (`--tags a --tags b`). Comma-separated `--tag a,b` variants have been removed.
+- **Job IDs are always `--id`**: `scm operations status` now uses `--id` (previously `--job-id`), matching `scm jobs status` and `scm jobs wait`.
+- **Insights `--mock` flags removed**: Use the `SCM_MOCK=1` environment variable instead (applies to all commands; `scm context test --mock` is unchanged).
+- **Layer3 subinterface VLAN flag**: Renamed to `--vlan-tag`.
+
+### Improved
+
+- Every `show` command supports `--output table|json|yaml` and `--max-results N`.
+- Every `load` command supports `--dry-run`; every `backup` command supports `--file`.
+
 ## Version 1.3.3
 
 **Released:** April 2026

docs-site/docs/about/troubleshooting.md

@@ -157,7 +157,7 @@ This format is produced by the `@handle_command_errors` decorator used across al
 :::tip
 Since errors go to stderr, you can separate them from normal output in scripts:
 ```bash
-scm set object address --folder Texas --name test --ip-netmask 10.0.0.1/32 2>errors.log
+scm set object address test --folder Texas --ip-netmask 10.0.0.1/32 2>errors.log
 ```
 :::
 

docs-site/docs/cli/deployment/bandwidth.md

@@ -19,14 +19,19 @@ Create or update a bandwidth allocation.
 ### Syntax
 
 ```bash
-scm set sase bandwidth-allocation [OPTIONS]
+scm set sase bandwidth-allocation NAME [OPTIONS]
 ```
 
+### Arguments
+
+| Argument | Description | Required |
+| --- | --- | --- |
+| `NAME` | Name of the bandwidth allocation | Yes |
+
 ### Options
 
 | Option | Description | Required |
 | --- | --- | --- |
-| `--name TEXT` | Name of the bandwidth allocation | Yes |
 | `--bandwidth INT` | Bandwidth value in Mbps | Yes |
 | `--spn-name-list TEXT` | SPN names (comma-separated if multiple) | Yes |
 | `--description TEXT` | Description for the bandwidth allocation | No |
@@ -41,8 +46,7 @@ Bandwidth allocations are global resources and do not require a `--folder` param
 #### Create a Basic Bandwidth Allocation
 
 ```bash
-$ scm set sase bandwidth-allocation \
-    --name Standard-Branch \
+$ scm set sase bandwidth-allocation Standard-Branch \
     --bandwidth 100 \
     --spn-name-list "branch-spn-1" \
     --description "Standard bandwidth for branch offices"
@@ -53,8 +57,7 @@ Created bandwidth allocation: Standard-Branch (100 Mbps)
 #### Create a Bandwidth Allocation with Multiple SPNs
 
 ```bash
-$ scm set sase bandwidth-allocation \
-    --name HQ-Bandwidth \
+$ scm set sase bandwidth-allocation HQ-Bandwidth \
     --bandwidth 1000 \
     --spn-name-list "HQ-SPN-1,HQ-SPN-2" \
     --description "High bandwidth for headquarters"
@@ -69,21 +72,26 @@ Delete a bandwidth allocation from SCM.
 ### Syntax
 
 ```bash
-scm delete sase bandwidth-allocation [OPTIONS]
+scm delete sase bandwidth-allocation NAME [OPTIONS]
 ```
 
+### Arguments
+
+| Argument | Description | Required |
+| --- | --- | --- |
+| `NAME` | Name of the bandwidth allocation to delete | Yes |
+
 ### Options
 
 | Option | Description | Required |
 | --- | --- | --- |
-| `--name TEXT` | Name of the bandwidth allocation to delete | Yes |
 | `--spn-name-list TEXT` | SPN names (comma-separated if multiple) | Yes |
 | `--force` | Skip confirmation prompt | No |
 
 ### Example
 
 ```bash
-$ scm delete sase bandwidth-allocation --name Standard-Branch --spn-name-list "branch-spn-1" --force
+$ scm delete sase bandwidth-allocation Standard-Branch --spn-name-list "branch-spn-1" --force
 ---> 100%
 Deleted bandwidth allocation: Standard-Branch
 ```
@@ -148,25 +156,32 @@ Display bandwidth allocation objects.
 ### Syntax
 
 ```bash
-scm show sase bandwidth-allocation [OPTIONS]
+scm show sase bandwidth-allocation [NAME] [OPTIONS]
 ```
 
+### Arguments
+
+| Argument | Description | Required |
+| --- | --- | --- |
+| `NAME` | Name of the bandwidth allocation to show; omit to list all | No |
+
 ### Options
 
 | Option | Description | Required |
 | --- | --- | --- |
-| `--name TEXT` | Name of the bandwidth allocation to show | No |
+| `--output, -o [table\|json\|yaml]` | Output format (default: table) | No |
+| `--max-results INTEGER` | Maximum number of results to display | No |
 
 :::note
-When no `--name` is specified, all items are listed by default.
+When no `NAME` is specified, all items are listed by default.
 :::
 
 ### Examples
 
 #### Show Specific Bandwidth Allocation
 
 ```bash
-$ scm show sase bandwidth-allocation --name HQ-Bandwidth
+$ scm show sase bandwidth-allocation HQ-Bandwidth
 ---> 100%
 Bandwidth Allocation: HQ-Bandwidth
   Allocated Bandwidth: 1000 Mbps

docs-site/docs/cli/deployment/bgp-routing.md

@@ -25,7 +25,7 @@ scm set sase bgp-routing [OPTIONS]
 
 | Option | Description | Required |
 | --- | --- | --- |
-| `--backbone-routing TEXT` | Backbone routing mode (no-asymmetric-routing, asymmetric-routing) | Yes |
+| `--backbone-routing TEXT` | Backbone routing mode (no-asymmetric-routing, asymmetric-routing-only, asymmetric-routing-with-load-share) | Yes |
 | `--routing-preference TEXT` | Routing preference (default, hot_potato_routing) | No |
 | `--accept-route-over-sc` | Accept routes over service connections | No |
 | `--outbound-routes TEXT` | Comma-separated outbound routes for services | No |
@@ -60,7 +60,7 @@ Updated BGP routing configuration
 
 ```bash
 $ scm set sase bgp-routing \
-    --backbone-routing asymmetric-routing \
+    --backbone-routing asymmetric-routing-only \
     --outbound-routes "10.0.0.0/8,172.16.0.0/12" \
     --withdraw-static-route
 ---> 100%
@@ -98,9 +98,15 @@ Display the current BGP routing configuration.
 ### Syntax
 
 ```bash
-scm show sase bgp-routing
+scm show sase bgp-routing [OPTIONS]
 ```
 
+### Options
+
+| Option | Description | Required |
+| --- | --- | --- |
+| `--output, -o [table\|json\|yaml]` | Output format (default: table) | No |
+
 ### Example
 
 ```bash