feat: move all the args to the end

CHANGELOG.adoc

@@ -23,6 +23,19 @@ always writes them under the .dfx/ directory.
 
 == DFX
 
+=== feat!: move all the flags to the end
+
+Command flags have been moved to a more traditional location; they are no longer positioned per subcommand, but instead are all positioned after the final subcommand. In prior versions, a command might look like:
+[source, bash]
+----
+dfx --identity alice canister --network ic --wallet "$WALLET" create --all
+----
+This command should now read:
+[source, bash]
+----
+dfx canister create --all --network ic --wallet "$WALLET" --identity alice
+----
+
 === fix: dfx now only adds candid:service metadata to custom canisters that have at least one build step
 
 This way, if a canister uses a premade canister wasm, dfx will use it as-is.

docs/cli-reference/dfx-canister.md

@@ -5,7 +5,7 @@ Use the `dfx canister` command with flags and subcommands to manage canister ope
 The basic syntax for running `dfx canister` commands is:
 
 ``` bash
-dfx canister [canister flags] subcommand [subcommand flags]
+dfx canister <subcommand> [flags]
 ```
 
 Depending on the `dfx canister` subcommand you specify, additional arguments, options, and flags might apply or be required. To view usage information for a specific `dfx canister` subcommand, specify the subcommand and the `--help` flag. For example, to see usage information for `dfx canister call`, you can run the following command:
@@ -49,37 +49,35 @@ dfx canister create --all
 If you want to register unique canister identifiers for the same project on the Internet Computer, you can run the following command:
 
 ``` bash
-dfx canister --network ic create --all
+dfx canister create --all --network ic
 ```
 
 The SDK comes with an alias of `ic`, which is configured to point to the Internet Computer. You can also pass a URL as a network option, or you can configure additional aliases in `dfx.json` under the `networks` configuration.
 
 To illustrate, you can call a canister and function running on a testnet using a command similar to the following:
 
 ``` bash
-dfx canister --network http://192.168.3.1:5678 call counter get
+dfx canister call counter get --network http://192.168.3.1:5678
 ```
 
-Note that you must specify the `--network` parameter before the canister operation (`create` or `call`) and any additional arguments such as the canister name (`counter`), and function (`get`).
-
 ## Performing a call through the wallet
 
 By default, most `dfx canister` commands to the Internet Computer are signed by and sent from your own principal. (Exceptions are commands that require cycles: `dfx canister create` and `dfx canister deposit-cycles`. Those automatically go through the wallet.) Occasionally, you may want to make a call from your wallet, e.g. when only your wallet is allowed to call a certain function. To send a call through your wallet, you can use the `--wallet` flag like this:
 
 ``` bash
-dfx canister --wallet <wallet id> status <canister name>
+dfx canister status <canister name> --wallet <wallet id>
 ```
 
 As a concrete example, if you want to request the status of a canister on the ic that is only controlled by your wallet, you would do the following:
 
 ``` bash
-dfx identity --network ic get-wallet
+dfx identity get-wallet --network ic
 ```
 
 This command outputs your wallet's principal (e.g. `22ayq-aiaaa-aaaai-qgmma-cai`) on the `ic` network. Using this id, you can then query the status of the canister (let's assume the canister is called `my_canister_name`) as follows:
 
 ``` bash
-dfx canister --network ic --wallet 22ayq-aiaaa-aaaai-qgmma-cai status
+dfx canister status --network ic --wallet 22ayq-aiaaa-aaaai-qgmma-cai
 ```
 
 ## dfx canister call 
@@ -272,7 +270,7 @@ dfx canister delete hello_world
 To delete all of the canisters you have deployed on the `ic` Internet Computer and configured in your `dfx.json`, you can run the following command:
 
 ``` bash
-dfx canister --network=ic delete --all
+dfx canister  delete --all--network=ic
 ```
 
 ## dfx canister deposit-cycles
@@ -488,11 +486,9 @@ If you want to deploy a canister on a testnet without changing the settings in y
 For example, you can specify a testnet URL by running a command similar to the following:
 
 ``` bash
-dfx canister --network http://192.168.3.1:5678 install --all
+dfx canister install --all --network http://192.168.3.1:5678
 ```
 
-Note that you must specify the network parameter before the canister operation (`install`) and before the canister name or `--all` flag.
-
 #### Allocating message processing
 
 The `--compute-allocation` options allows you to allocate computing resources as a percentage in the range of 0 to 100 to indicate how often your canister should be scheduled for execution.
@@ -677,7 +673,7 @@ You can specify the following arguments for the `dfx canister sign` command.
 
 Use the `dfx canister sign` command to create a signed `message.json` file using the selected identity by running a command similar to the following:
 
-`dfx canister --network=ic sign --expire-after=1h rno2w-sqaaa-aaaaa-aaacq-cai create_neurons ‘(“PUBLIC_KEY”)’`
+`dfx canister sign --network=ic --expire-after=1h rno2w-sqaaa-aaaaa-aaacq-cai create_neurons ‘(“PUBLIC_KEY”)’`
 
 This command illustrates how to creates a `message.json` file to create neurons on the Internet Computer specified by the `ic` alias, that is signed using your principal identifier as the message sender and with an expiration window that ends in one hour.
 
@@ -735,7 +731,7 @@ dfx canister start hello_world
 To start all of the canisters you have deployed on the `ic` Internet Computer, you can run the following command:
 
 ``` bash
-dfx canister --network=ic start --all
+dfx canister start --all --network=ic
 ```
 
 ## dfx canister status
@@ -780,7 +776,7 @@ dfx canister status hello_world
 To check the status for all of the canisters you have deployed on the `ic` Internet Computer, you can run the following command:
 
 ``` bash
-dfx canister --network=ic status --all
+dfx canister status --all --network=ic
 ```
 
 ## dfx canister stop
@@ -827,7 +823,7 @@ dfx canister stop hello_world
 To stop all of the canisters you have deployed on the `ic` Internet Computer, you can run the following command:
 
 ``` bash
-dfx canister --network=ic stop --all
+dfx canister stop --all --network=ic
 ```
 
 ## dfx canister uninstall-code
@@ -874,7 +870,7 @@ dfx canister uninstall-code hello_world
 To uninstall all of the canisters you have deployed on the `ic` Internet Computer, you can run the following command:
 
 ``` bash
-dfx canister --network=ic uninstall-code --all
+dfx canister uninstall-code --all --network=ic
 ```
 
 ## dfx canister update-settings

docs/cli-reference/dfx-identity.md

@@ -104,7 +104,7 @@ dfx identity get-wallet
 To display the canister identifier for the wallet canister associated with your identity on a specific testnet, you might run a command similar to the following:
 
 ``` bash
-dfx identity --network=https://192.168.74.4 get-wallet
+dfx identity get-wallet --network=https://192.168.74.4
 ```
 
 ## dfx identity import
@@ -344,7 +344,7 @@ If you use more than one principal for your identity, you might have access to m
 For example, you might store the wallet canister identifier in an environment variable, then invoke the `dfx identity set-wallet` command to use that wallet canister for additional operations by running the following:
 
     export WALLET_CANISTER_ID=$(dfx identity get-wallet)
-    dfx identity --network=https://192.168.74.4 set-wallet --canister-name ${WALLET_CANISTER_ID}
+    dfx identity set-wallet --canister-name ${WALLET_CANISTER_ID} --network=https://192.168.74.4
 
 ## dfx identity use
 

docs/cli-reference/dfx-ledger.md

@@ -7,7 +7,7 @@ This command can be used to make ICP utility token transactions from one caniste
 The basic syntax for running `dfx ledger` commands is:
 
 ``` bash
-dfx ledger [options] [subcommand]
+dfx ledger [subcommand] [options]
 ```
 
 Depending on the `dfx ledger` subcommand you specify, additional arguments, options, and flags might apply. For reference information and examples that illustrate using `dfx ledger` commands, select an appropriate command.
@@ -68,7 +68,7 @@ Use the `dfx ledger balance` command to print your account balance or that of an
 ### Basic usage
 
 ``` bash
-dfx ledger --network ic balance [of] [flag]
+dfx ledger balance [of] [flag] --network ic
 ```
 
 ### Flags
@@ -93,7 +93,7 @@ You can specify the following argument for the `dfx ledger balance` command.
 You can use the `dfx ledger balance` command to check the balance of another user. For example, you can run the following command to see the ICP utlity tokens associated with a known Account Identifier:
 
 ``` bash
-dfx ledger --network ic balance 03e3d86f29a069c6f2c5c48e01bc084e4ea18ad02b0eec8fccadf4487183c223
+dfx ledger balance 03e3d86f29a069c6f2c5c48e01bc084e4ea18ad02b0eec8fccadf4487183c223 --network ic
 ```
 
 This command displays an ICP amount similar to the following:
@@ -107,7 +107,7 @@ Use the `dfx ledger create-canister` command to convert ICP tokens to cycles and
 ### Basic usage
 
 ``` bash
-dfx ledger --network ic create-canister controller [options]  [flag]
+dfx ledger create-canister <controller> [options]  [flag] --network ic
 ```
 
 ### Flags
@@ -144,7 +144,7 @@ You can specify the following argument for the `dfx ledger create-canister` comm
 To create a new canister with cycles, transfer ICP tokens from your ledger account by running a command similar to the following:
 
 ``` bash
-dfx ledger --network ic create-canister tsqwz-udeik-5migd-ehrev-pvoqv-szx2g-akh5s-fkyqc-zy6q7-snav6-uqe --amount 1.25
+dfx ledger create-canister tsqwz-udeik-5migd-ehrev-pvoqv-szx2g-akh5s-fkyqc-zy6q7-snav6-uqe --amount 1.25 --network ic
 ```
 
 This command converts the number of ICP tokens you specify for the `--amount` argument into cycles, and associates the cycles with a new canister identifier controlled by the principal you specify.
@@ -159,7 +159,7 @@ If the transaction is successful, the ledger records the event and you should se
 You can create a new canister by specifying separate values for ICP tokens and e8s by running a command similar to the following:
 
 ``` bash
-dfx ledger --network ic create-canister tsqwz-udeik-5migd-ehrev-pvoqv-szx2g-akh5s-fkyqc-zy6q7-snav6-uqe --icp 3 --e8s 5000
+dfx ledger create-canister tsqwz-udeik-5migd-ehrev-pvoqv-szx2g-akh5s-fkyqc-zy6q7-snav6-uqe --icp 3 --e8s 5000 --network ic
 ```
 
 ## dfx ledger fabricate-cycles
@@ -261,7 +261,7 @@ You can specify the following argument for the `dfx ledger notify` command.
 The following example illustrates sending a `notify` message to the ledger in response to a `_send+` transaction that was recorded at the block height `75948`.
 
 ``` bash
-dfx ledger --network ic notify 75948 tsqwz-udeik-5migd-ehrev-pvoqv-szx2g-akh5s-fkyqc-zy6q7-snav6-uqe
+dfx ledger notify 75948 tsqwz-udeik-5migd-ehrev-pvoqv-szx2g-akh5s-fkyqc-zy6q7-snav6-uqe --network ic
 ```
 
 ## dfx ledger top-up
@@ -271,7 +271,7 @@ Use the `dfx ledger top-up` command to top up a canister with cycles minted from
 ### Basic usage
 
 ``` bash
-dfx ledger --network ic top-up [options] canister [flag]
+dfx ledger top-up [options] canister [flag] --network ic
 ```
 
 ### Flags
@@ -310,7 +310,7 @@ You can use the `dfx ledger top-up` command to top up the cycles of a specific c
 For example, you can run the following command to top-up a cycles wallet canister deployed on the Internet Computer with 1 ICP worth of cycles:
 
 ``` bash
-dfx ledger --network ic top-up --icp 1 5a46r-jqaaa-aaaaa-qaadq-cai
+dfx ledger top-up --icp 1 5a46r-jqaaa-aaaaa-qaadq-cai --network ic
 ```
 
 This command displays output similar to the following:
@@ -374,7 +374,7 @@ This command displays output similar to the following:
 You can check the balance of this account by running the following command:
 
 ``` bash
-dfx ledger --network ic balance
+dfx ledger balance --network ic
 ```
 
 This command displays output similar to the following:
@@ -384,11 +384,11 @@ This command displays output similar to the following:
 Use the `dfx ledger transfer` command to send some of your ICP balance to another known destination using the following command:
 
 ``` bash
-dfx ledger --network ic transfer dd81336dbfef5c5870e84b48405c7b229c07ad999fdcacb85b9b9850bd60766f --memo 12345 --icp 1
+dfx ledger transfer dd81336dbfef5c5870e84b48405c7b229c07ad999fdcacb85b9b9850bd60766f --memo 12345 --icp 1 --network ic
 ```
 
 This command displays output similar to the following:
 
     Transfer sent at BlockHeight: 59513
 
-You can then use the `dfx ledger --network ic balance` command to check that your account balance reflects the transaction you just made.
+You can then use the `dfx ledger balance --network ic` command to check that your account balance reflects the transaction you just made.

docs/cli-reference/dfx-parent.md

@@ -7,7 +7,7 @@ Use the `dfx` parent command with flags and subcommands to specify the operation
 ## Basic usage
 
 ``` bash
-dfx [option] [subcommand] [flag]
+dfx [subcommand] [flag]
 ```
 
 ## Flags
@@ -17,7 +17,7 @@ You can use the following optional flags with the `dfx` parent command or with a
 | Flag                 | Description                                     |
 |----------------------|-------------------------------------------------|
 | `-h`, `--help`       | Displays usage information.                     |
-| ` -q`, `--quiet` | Suppresses informational messages.              |
+| `-q`, `--quiet`      | Suppresses informational messages.              |
 | `-v`, `--verbose`    | Displays detailed information about operations. |
 | `-V`, `--version`    | Displays version information.                   |
 
@@ -27,7 +27,7 @@ You can use the following options with the `dfx` command.
 
 | Option                         | Description                                     |
 |--------------------------------|-------------------------------------------------|
-| `-- identity <identity>`       | Specifies the user identity to use when running a command.                                                     |
+| `--identity <identity>`        | Specifies the user identity to use when running a command.                                                     |
 | `--logfile <logfile>`          | Writes log file messages to the specified log file name if you use the `--log file` logging option.              |
 | `--log <logmode>`              | Specifies the logging mode to use. + You can set the log mode to one of the following:<br />- `stderr` to log messages to the standard error facility.<br />- `tee` to write messages to both standard output and to a specified file name.<br />- `file` to write messages to a specified file name.<br />The default logging mode is stderr.|
 
@@ -77,15 +77,15 @@ You can use the `--verbose` and `--quiet` flags to increment or decrement the lo
 Adding a `--quiet` flag decreases the logging level. For example, to remove all messages, you can run a command similar the following:
 
 ``` bash
-dfx -qqqq build
+dfx build -qqqq
 ```
 
 Keep in mind that using TRACE level logging (`--vv`) generates a lot of log messages that can affect performance and should only be used when required for troubleshooting or analysis.
 
 To output log messages to a file named `newlog.txt` and display the messages on your terminal when creating a new project, you can run a command similar to the following:
 
 ``` bash
-dfx --log tee --logfile newlog.txt new hello_world
+dfx new hello_world --log tee --logfile newlog.txt
 ```
 
 ### Specifying a user identity
@@ -96,4 +96,4 @@ In the most common use case, you use the `--identity` option to call specific ca
 
 For example, you might want to test whether the `devops` user identity can call the `modify_profile` function for the `accounts` canister by running the following command:
 
-    dfx --identity devops canister call accounts modify_profile '("Kris Smith")'
+    dfx canister call accounts modify_profile '("Kris Smith")' --identity devops

docs/cli-reference/dfx-wallet.md

@@ -140,7 +140,7 @@ You can use the following optional flags with the `dfx wallet add-controller` co
 You can use the `dfx wallet addresses` command to retrieve information on the addresses in your wallet's address book. For example:
 
 ```
-dfx wallet --network ic addresses
+dfx wallet addresses --network ic
 ```
 
 The command displays the controllers and custodians for the cycles wallet with output similar to the following:

docs/cli-reference/index.md

@@ -7,7 +7,7 @@ You can use the `dfx` parent command with different flags and subcommands to per
 The basic syntax for running `dfx` commands is:
 
 ``` bash
-dfx [option] [subcommand] [flag]
+dfx [subcommand] [flag]
 ```
 
 Depending on the subcommand, the options and flags you specify might apply to the parent command or to a specific subcommand. For example, the flags for enabling or suppressing verbose logging are specified for the `dfx` parent command, then applied to any subcommands.

e2e/tests-dfx/basic-project.bash

@@ -41,7 +41,7 @@ teardown() {
     assert_eq '("Hello, Blueberry!")'
 
     # Call using the wallet's call forwarding
-    assert_command dfx canister --wallet="$(dfx identity get-wallet)" call --async hello_backend greet Blueberry
+    assert_command dfx canister call --async hello_backend greet Blueberry --wallet="$(dfx identity get-wallet)"
     # At this point $output is the request ID.
     # shellcheck disable=SC2154
     assert_command dfx canister request-status "$stdout" "$(dfx identity get-wallet)"
@@ -93,7 +93,7 @@ teardown() {
     assert_eq "(1_337 : nat)"
 
     # Call using the wallet's call forwarding
-    assert_command dfx canister --wallet="$(dfx identity get-wallet)" call hello_backend read --async
+    assert_command dfx canister call hello_backend read --async --wallet="$(dfx identity get-wallet)"
     assert_command dfx canister request-status "$stdout" "$(dfx identity get-wallet)"
     assert_eq '(variant { 17_724 = record { 153_986_224 = blob "DIDL\00\01}\b9\0a" } })'
 

e2e/tests-dfx/build.bash

@@ -178,14 +178,14 @@ teardown() {
 
 @test "build succeeds with network parameter" {
   dfx_start
-  dfx canister --network local create --all
+  dfx canister create --all --network local
   assert_command dfx build --network local
 }
 
 @test "build succeeds with URL as network parameter" {
     dfx_start
     webserver_port=$(get_webserver_port)
-    dfx canister --network "http://127.0.0.1:$webserver_port" create --all
+    dfx canister create --all --network "http://127.0.0.1:$webserver_port"
     assert_command dfx build --network "http://127.0.0.1:$webserver_port"
 }
 
@@ -194,7 +194,7 @@ teardown() {
 
   setup_actuallylocal_network
 
-  assert_command dfx canister --network actuallylocal create --all
+  assert_command dfx canister create --all --network actuallylocal
   assert_command dfx build --network actuallylocal
 }
 
@@ -203,7 +203,7 @@ teardown() {
   setup_actuallylocal_network
   assert_command dfx_set_wallet
 
-  assert_command dfx canister --network actuallylocal create --all
+  assert_command dfx canister create --all --network actuallylocal
   assert_command dfx build --network actuallylocal
 }
 
@@ -220,7 +220,7 @@ teardown() {
   setup_actuallylocal_network
   assert_command dfx_set_wallet
 
-  dfx canister --network actuallylocal create --all
+  dfx canister create --all --network actuallylocal
   assert_command dfx build --network actuallylocal
   assert_command ls .dfx/actuallylocal/canisters/e2e_project_backend/
   assert_command ls .dfx/actuallylocal/canisters/e2e_project_backend/e2e_project_backend.wasm