diff --git a/docs/cli-reference/dfx-build.mdx b/docs/cli-reference/dfx-build.mdx index 991ff38071..8f640f3311 100644 --- a/docs/cli-reference/dfx-build.mdx +++ b/docs/cli-reference/dfx-build.mdx @@ -4,12 +4,12 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -Use the `dfx build` command to compile your program into a WebAssembly module that can be deployed on the IC. You can use this command to compile all of the programs that are defined for a project in the project’s `dfx.json` configuration file or a specific canister. - -Note that you can only run this command from within the project directory structure. For example, if your project name is `hello_world`, your current working directory must be the `hello_world` top-level project directory or one of its subdirectories. +Use the `dfx build` command to compile your program into a WebAssembly module that can be deployed on ICP. You can use this command to compile all of the canisters that are defined in the project’s `dfx.json` configuration file or compile only a specific canister. The `dfx build` command looks for the source code to compile using the information you have configured under the `canisters` section in the `dfx.json` configuration file. +Note that you can only run this command from within the project directory structure. For example, if your project name is `hello_world`, your current working directory must be the `hello_world` top-level project directory or one of its subdirectories. + ## Basic usage ``` bash @@ -22,7 +22,7 @@ You can use the following optional flags with the `dfx build` command. | Flag | Description | | --------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `--check` | Builds canisters using a temporary, hard-coded, locally-defined canister identifier for testing that your program compiles without connecting to the IC. | +| `--check` | Builds canisters using a temporary, hard-coded, locally-defined canister ID for testing that the canister compiles without connecting to ICP. | ## Options @@ -31,7 +31,7 @@ You can specify the following options for the `dfx build` command. | Option | Description | | --------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--network ` | Specifies the network alias or URL you want to connect to. You can use this option to override the network specified in the `dfx.json` configuration file. | -| `--output-env-file` | Writes dfx environment variables to a provided path. Overrides the `output_env_file` configuration from `dfx.json` if passed. | +| `--output-env-file` | Writes `dfx` environment variables to a provided path. Overrides the `output_env_file` configuration from `dfx.json` if passed. | ## Arguments @@ -39,14 +39,11 @@ You can specify the following arguments for the `dfx build` command. | Argument | Description | | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `--all` | Builds all of the canisters configured in the project’s `dfx.json` file. | -| `canister_name` | Specifies the name of the canister you want to build. If you are not using the `--all` option, you can continue to use `dfx build` or provide a canister name as an argument (the canister name must match at least one name that you have configured in the `canisters` section of the `dfx.json` configuration file for your project.) | +| `--all` | Builds all canisters configured in the project’s `dfx.json` file. | +| `canister_name` | Specifies the name of the canister you want to build. If you are not using the `--all` option, you can continue to use `dfx build` or provide a canister name as an argument. The canister name must match at least one name that you have configured in the `canisters` section of the `dfx.json` configuration file for your project. | ## Examples -You can use the `dfx build` command to build one or more WebAssembly modules from the programs specified in the `dfx.json` configuration file under the `canisters` key. For example, if your `dfx.json` configuration file defines one `hello_world_backend` canister and one `hello_world_frontend` canister, then running `dfx build` compiles two WebAssembly modules. - -Note that the file name and path to the programs on your file system must match the information specified in the `dfx.json` configuration file. In this example, the `hello_world_backend` canister contains the main program code and the `hello_world_frontend` canister store frontend code and assets. If you want to keep the `hello_world_frontend` canister defined in the `dfx.json` file, but only build the backend program, you could run the following command: @@ -54,9 +51,9 @@ In this example, the `hello_world_backend` canister contains the main program co dfx build hello_world_backend ``` -Building a specific canister is useful when you have multiple canisters defined in the dfx.json file, but want to test and debug operations for canisters independently. +Building a specific canister is useful when you have multiple canisters defined in the `dfx.json` file, but want to test and debug operations for canisters independently. -To test whether a canister compiles without connecting to the IC or the local development environment, you would run the following command: +To test whether a canister compiles without connecting to the mainnet or the local development environment, you would run the following command: ``` bash dfx build --check @@ -64,4 +61,4 @@ dfx build --check ## Management canister -If `dfx` detects that your Motoko project is importing the Management Canister (e.g. `import Management "ic:aaaaa-aa";`) it will automatically provide the Candid interface for the Management Canister during the build. +If `dfx` detects that your Motoko project is importing the management canister (e.g. `import Management "ic:aaaaa-aa";`) it will automatically provide the Candid interface for the management canister during the build. diff --git a/docs/cli-reference/dfx-cache.mdx b/docs/cli-reference/dfx-cache.mdx index 6611e89c3e..ea347195be 100644 --- a/docs/cli-reference/dfx-cache.mdx +++ b/docs/cli-reference/dfx-cache.mdx @@ -4,7 +4,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -Use the `dfx cache` command with flags and subcommands to manage the `dfx` version cache. +Use the `dfx cache` command to manage the `dfx` version cache. When a version of `dfx` is installed, it is added to the version cache. The basic syntax for running `dfx cache` commands is: @@ -17,7 +17,7 @@ Depending on the `dfx cache` subcommand you specify, additional arguments, optio | Command | Description | |----------------------------|-------------------------------------------------------------------------------| | [`delete`](#delete) | Deletes the specified version of `dfx` from the local cache. | -| `help` | Displays usage information message for a specified subcommand. | +| `help` | Displays usage information message for the `dfx cache` command. | | [`install`](#install) | Installs the specified version of `dfx` from the local cache. | | [`list`](#_dfx_cache_list) | Lists the versions of `dfx` currently installed and used in current projects. | | [`show`](#_dfx_cache_show) | Show the path of the cache used by this version of the `dfx` executable. | @@ -30,7 +30,7 @@ dfx cache delete --help ## dfx cache delete -Use the `dfx cache delete` command to delete a specified version of the IC SDK from the version cache on the local computer. +Use the `dfx cache delete` command to delete a specified version of `dfx` from the version cache on the local computer. ### Basic usage @@ -46,9 +46,7 @@ You can specify the following argument for the `dfx cache delete` command. |-----------|--------------------------------------------------------------------| | `version` | Specifies the version of `dfx` you to delete from the local cache. | -### Examples - -You can use the `dfx cache delete` command to permanently delete versions of the IC SDK that you no longer want to use. For example, you can run the following command to delete the IC SDK version `0.6.2`: +### Example ``` bash dfx cache delete 0.6.2 @@ -56,7 +54,7 @@ dfx cache delete 0.6.2 ## dfx cache install -Use the `dfx cache install` command to install the IC SDK using the version currently found in the `dfx` cache. +Use the `dfx cache install` command to install the latest `dfx` version currently found in the `dfx` cache. ### Basic usage @@ -64,9 +62,7 @@ Use the `dfx cache install` command to install the IC SDK using the version curr dfx cache install [flag] ``` -### Examples - -You can use the `dfx cache install` command to force the installation of `dfx` from the version in the cache. For example, you can run the following command to install `dfx`: +### Example ``` bash dfx cache install @@ -74,9 +70,9 @@ dfx cache install ## dfx cache list -Use the `dfx cache list` command to list the IC SDK versions you have currently installed and used in projects. +Use the `dfx cache list` command to list `dfx` versions you have currently installed and used in projects. -If you have multiple versions of the IC SDK installed, the cache list displays an asterisk (\*) to indicate the currently active version. +If you have multiple versions of `dfx` installed, the cache list displays an asterisk (\*) to indicate the currently active version. ### Basic usage @@ -84,15 +80,13 @@ If you have multiple versions of the IC SDK installed, the cache list displays a dfx cache list [flag] ``` -### Examples - -You can use the `dfx cache list` command to list the IC SDK versions you have currently installed and used in projects. For example, you can run the following command to list versions of the IC SDK found in the cache: +### Example ``` bash dfx cache list ``` -This command displays the list of the IC SDK versions found similar to the following: +This command displays the list of `dfx` versions found similar to the following: ``` bash 0.6.4 * @@ -102,7 +96,7 @@ This command displays the list of the IC SDK versions found similar to the follo ## dfx cache show -Use the `dfx cache show` command to display the full path to the cache used by the IC SDK version you are currently using. +Use the `dfx cache show` command to display the full path to the cache used by the `dfx` version you are currently using. ### Basic usage @@ -110,9 +104,7 @@ Use the `dfx cache show` command to display the full path to the cache used by t dfx cache show [flag] ``` -### Examples - -You can use the `dfx cache show` command to display the path to the cache used by the IC SDK version you are currently using: +### Example ``` bash dfx cache show diff --git a/docs/cli-reference/dfx-canister.mdx b/docs/cli-reference/dfx-canister.mdx index a8779f89c3..1eec11466e 100644 --- a/docs/cli-reference/dfx-canister.mdx +++ b/docs/cli-reference/dfx-canister.mdx @@ -4,9 +4,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -Use the `dfx canister` command with options and subcommands to manage canister operations and interaction with the -Internet Computer or the local development environment. In most cases, you use `dfx canister` subcommands after -you compile a program to manage the canister lifecycle and to perform key tasks such as calling program functions. +Use the `dfx canister` command with options and subcommands to manage canister operations and interaction with the ICP mainnet or the local development environment. In most cases, you use `dfx canister` subcommands to manage the canister lifecycle and to perform key tasks such as calling program functions. The basic syntax for running `dfx canister` commands is: @@ -27,7 +25,7 @@ For reference information and examples that illustrate using `dfx canister` comm | Command | Description | |----------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------| | [`call`](#dfx-canister-call) | Calls a specified method on a deployed canister. | -| [`create`](#dfx-canister-create) | Creates an empty canister and associates the assigned Canister ID to the canister name. | +| [`create`](#dfx-canister-create) | Creates an empty canister and assigns a canister ID to the canister name. | | [`delete`](#dfx-canister-delete) | Deletes a currently stopped canister. | | [`deposit-cycles`](#dfx-canister-deposit-cycles) | Deposit cycles into the specified canister. | | `help` | Displays usage information message for a specified subcommand. | @@ -35,22 +33,22 @@ For reference information and examples that illustrate using `dfx canister` comm | [`info`](#dfx-canister-info) | Get the hash of a canister’s Wasm module and its current controller. | | [`install`](#dfx-canister-install) | Installs compiled code in a canister. | | [`logs`](#dfx-canister-logs) | Returns the logs from a canister. | -| [`metadata`](#dfx-canister-metadata) | Displays metadata in a canister. | +| [`metadata`](#dfx-canister-metadata) | Displays metadata of a canister. | | [`request-status`](#dfx-canister-request-status) | Requests the status of a call to a canister. | | [`send`](#dfx-canister-send) | Send a previously-signed message. | | [`set-id`](#dfx-canister-id) | Sets the identifier of a canister. | -| [`sign`](#dfx-canister-send) | Sign a canister call and generate message file. | +| [`sign`](#dfx-canister-send) | Sign a canister call and generate a message file. | | [`start`](#dfx-canister-start) | Starts a stopped canister. | -| [`status`](#dfx-canister-status) | Returns the current status of a canister as defined [here](https://internetcomputer.org/docs/current/references/ic-interface-spec#ic-canister_status). | +| [`status`](#dfx-canister-status) | Returns the current status of a canister as [defined](https://internetcomputer.org/docs/references/ic-interface-spec#ic-canister_status). | | [`stop`](#dfx-canister-stop) | Stops a currently running canister. | | [`uninstall-code`](#dfx-canister-uninstall-code) | Uninstalls a canister, removing its code and state. Does not delete the canister. | | [`update-settings`](#dfx-canister-update-settings) | Update one or more of a canister's settings (i.e its controller, compute allocation, or memory allocation.). | -| [`url`](#dfx-canister-url) | Displays the url of a canister. | +| [`url`](#dfx-canister-url) | Displays the URL of a canister. | ## Overriding the default deployment environment By default, `dfx canister` commands run on the local development environment specified in the `dfx.json` file. If -you want to send a `dfx canister` subcommand to the Internet Computer or a testnet without changing the settings in +you want to send a `dfx canister` subcommand to the mainnet or the playground without changing the settings in your `dfx.json` configuration file, you can explicitly specify the URL to connect to using the `--network` option. For example, to register unique canister identifiers for a project on the local development environment, you can @@ -60,61 +58,58 @@ run the following command: dfx canister create --all ``` -If you want to register unique canister identifiers for the same project on the Internet Computer, you can run the +If you want to register unique canister identifiers for the same project on the mainnet, you can run the following command: ``` bash 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 +`dfx` comes with an alias of `ic`, which is configured to point to the mainnet. You can also pass a URL as a network option, or you can configure additional aliases in `dfx.json` under the `networks` configuration, or in `$HOME/.config/dfx/networks.json`. -To illustrate, you can call a canister and function running on a testnet using a command similar to the following: +To illustrate, you can call a canister and function running on a local custom network using a command similar to the following: ``` bash dfx canister call counter get --network http://192.168.3.1:5678 ``` -## Performing a call through the wallet +## Performing a call through a cycles 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` option. -You will either specify the wallet's principal, or the name of an identity associated with a wallet. +By default, most `dfx canister` commands to the mainnet are signed by and sent from your own principal. -### Specifying a wallet by principal +Exceptions are commands that require cycles: `dfx canister create` and `dfx canister deposit-cycles`. These automatically go through the cycles wallet. Occasionally, you may want to make a call from the cycles wallet, e.g. when only the wallet is allowed to call a certain function. To send a call through the cycles wallet, you can use the `--wallet` option. -To specify a wallet by principal, pass the principal directly. +You will either specify the cycles wallet's principal, or the name of an identity associated with a cycles wallet. + +### Specifying a cycles wallet by principal + +To specify a cycles wallet by principal, pass the principal directly. ``` bash dfx canister status --wallet ``` -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: +As a concrete example, if you want to request the status of a canister on the mainnet that is only controlled by your wallet, +you would run the following: ``` bash 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: +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 as follows: ``` bash dfx canister status --network ic --wallet 22ayq-aiaaa-aaaai-qgmma-cai ``` -### Specifying a wallet by identity name +### Specifying a cycles wallet by identity name -In the previous example, we first looked up the principal of the currently -selected wallet. We can avoid this step by specifying the name of an identity, -in which case dfx will look up the wallet's principal for us. +You can also specify the name of an identity, in which case `dfx` will look up the cycles wallet's principal. -For example, the following command will query the status of a canister, -using the wallet associated with the default identity on the ic network: +For example, the following command will query the status of a canister, using the cycles wallet associated with the default identity on the mainnet: ``` bash dfx canister status --network ic --wallet default @@ -145,10 +140,10 @@ You can use the following options with the `dfx canister call` command. |-----------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `--argument-file ` | Specifies the file from which to read the argument to pass to the method. Stdin may be referred to as `-`. | | `--async` | Specifies not to wait for the result of the call to be returned by polling the local development environment. Instead return a response ID. | -| `--candid ` | Provide the .did file with which to decode the response. Overrides value from dfx.json for project canisters. | +| `--candid ` | Provide the .did file with which to decode the response. Overrides value from `dfx.json` for project canisters. | | `--impersonate ` | Specifies a principal on behalf of which requests to a local PocketIC instance are sent. | | `--output ` | Specifies the output format to use when displaying a method’s return result. The valid values are `idl`, 'json', `pp` and `raw`. The `pp` option is equivalent to `idl`, but is pretty-printed. | -| `--query` | Sends a query request instead of an update request. For information about the difference between query and update calls, see [Canisters include both program and state](https://internetcomputer.org/docs/current/concepts/canisters-code). | +| `--query` | Sends a query request instead of an update request. For information about the difference between query and update calls, see [Canisters include both program and state](https://internetcomputer.org/docs/building-apps/essentials/canisters). | | `--random ` | Specifies the config for generating random arguments. | | `--type ` | Specifies the data format for the argument when making the call using an argument. The valid values are `idl` and `raw`. | | `--update` | Sends an update request to a canister. This is the default if the method is not a query method. | @@ -160,34 +155,29 @@ You can specify the following arguments for the `dfx canister call` command. | Argument | Description | |-----------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `canister_name` | Specifies the name of the canister to call. The canister name is a required argument and should match the name you have configured for a project in the `canisters` section of the `dfx.json` configuration file. | +| `canister_name` | Specifies the name of the canister to call. The canister name is a required argument and should match the name you have configured for a canister in the `canisters` section of the `dfx.json` configuration file. | | `method_name` | Specifies the method name to call on the canister. The canister method is a required argument. | -| `argument` | Specifies the argument to pass to the method | +| `argument` | Specifies the argument to pass to the method. | #### Specifies the argument to pass to the method -Depending on your program logic, the argument can be a required or optional argument. You can specify a data format type using the `--type` option if you pass an argument to the canister. By default, you can specify arguments using the [Candid](/docs/current/references/candid-ref) (`idl`) syntax for data values. For information about using Candid and its supported types, see [Interact with a service in a terminal](/docs/current/developer-docs/smart-contracts/candid/candid-howto#idl-syntax) and [supported types](/docs/current/references/candid-ref#supported-types). You can use `raw` as the argument type if you want to pass raw bytes. +Depending on your program logic, the argument can be a required or optional argument. You can specify a data format type using the `--type` option if you pass an argument to the canister. By default, you can specify arguments using the [Candid](https://internetcomputer.org/docs/references/candid-ref) (`idl`) syntax for data values. You can use `raw` as the argument type if you want to pass raw bytes. ### Examples -You can use the `dfx canister call` command to invoke specific methods—with or without arguments—after you have deployed -the canister using the `dfx canister install` command. For example, to invoke the `get` method for a canister with -a `canister_name` of `counter`, you can run the following command: +You can use the `dfx canister call` command to invoke specific methods, with or without arguments, after you have installed the canister's code using the `dfx canister install` command. For example, to invoke the `get` method for a canister with a `canister_name` of `counter`, you can run the following command: ``` bash dfx canister call counter get --async ``` -In this example, the command includes the `--async` option to indicate that you want to make a separate `request-status` -call rather than waiting to poll the local development environment or the Internet Computer for the result. -The `--async` option is useful when processing an operation might take some time to complete. The option enables you to -continue performing other operations then check for the result using a separate `dfx canister request-status` command. -The returned result will be displayed as the IDL textual format. +In this example, the command includes the `--async` option to indicate that you want to make a separate `request-status` call rather than waiting to poll the local development environment or the mainnet for the result. + +The `--async` option is useful when processing an operation might take some time to complete. The option enables you to continue performing other operations then check for the result using a separate `dfx canister request-status` command. The returned result will be displayed as the IDL textual format. #### Using the IDL syntax -You can explicitly specify that you are passing arguments using the IDL syntax by running commands similar to the -following for a Text data type: +You can explicitly specify that you are passing arguments using the IDL syntax by running commands similar to the following for a `Text` data type: ``` bash dfx canister call hello greet --type idl '("Lisa")' @@ -224,9 +214,7 @@ This example uses the raw data type to pass a hexadecimal to the `greet` functio The `--output json` option formats the output as JSON. -Candid types don't map 1:1 to JSON types. - -Notably, the following Candid types map to strings rather than numbers: nat, nat64, int, int64. +Candid types don't map 1:1 to JSON types. Notably, the following Candid types map to strings rather than numbers: `nat`, `nat64`, `int`, `int64`. These are the mappings: @@ -257,7 +245,7 @@ These are the mappings: Use the `dfx canister create` command to register one or more canister identifiers without compiled code. The new canister principals are then recorded in `canister_ids.json` for non-local networks. You must be connected to the local -canister execution environment or the Internet Computer to run this command. +development or the mainnet to run this command. Note that you can only run this command from within the project directory structure. For example, if your project name is `hello_world`, your current working directory must be the `hello_world` top-level project directory or one of its @@ -277,20 +265,20 @@ You can use the following options with the `dfx canister create` command. |-------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `-c`, `--compute-allocation ` | Specifies the canister's compute allocation. This should be a percent in the range [0..100]. | | `--controller ` | Specifies the identity name or the principal of the new controller. | -| `--created-at-time ` | Transaction timestamp, in nanoseconds, for use in controlling transaction deduplication, default is system time. https://internetcomputer.org/docs/current/developer-docs/integrations/icrc-1/#transaction-deduplication- | +| `--created-at-time ` | Transaction timestamp, in nanoseconds, for use in controlling transaction deduplication, default is system time. | | `--from-subaccount ` | Subaccount of the selected identity to spend cycles from. | -| `--memory-allocation ` | Specifies how much memory the canister is allowed to use in total. This should be a value in the range [0..12 GiB]. A setting of 0 means the canister will have access to memory on a “best-effort” basis: It will only be charged for the memory it uses, but at any point in time may stop running if it tries to allocate more memory when there isn’t space available on the subnet. | +| `--memory-allocation ` | Specifies how much memory the canister is allowed to use in total. This should be a value in the range [0..12 GiB]. A setting of 0 means the canister will have access to memory on a “best-effort” basis. It will only be charged for the memory it uses, but at any point in time may stop running if it tries to allocate more memory when there isn’t space available on the subnet. | | `--reserved-cycles-limit ` | Specifies the upper limit for the canister's reserved cycles. | | `--wasm-memory-limit ` | Specifies a soft upper limit for the canister's heap memory. | | `--wasm-memory-threshold ` | Specifies a threshold remaining amount of memory before the canister's low-memory hook runs. | -| `--log-viewer ` | Specifies the principal as an allowed viewers. Can be specified more than once. Cannot be used with `--log-visibility`. | +| `--log-viewer ` | Specifies the principal as an allowed viewer. Can be specified more than once. Cannot be used with `--log-visibility`. | | `--log-visibility ` | Specifies who can read the canister's logs: "controllers" or "public". For custom allowed viewers, use `--log-viewer`. | -| `--no-wallet` | Performs the call with the user Identity as the Sender of messages. Bypasses the Wallet canister. Enabled by default. | +| `--no-wallet` | Performs the call with the user identity as the sender of messages. Bypasses the wallet canister. Enabled by default. | | `--with-cycles ` | Specifies the initial cycle balance to deposit into the newly created canister. The specified amount needs to take the canister create fee into account. This amount is deducted from the wallet's cycle balance. | -| `--specified-id ` | Attempts to create the canister with this Canister ID | +| `--specified-id ` | Attempts to create the canister with this canister ID. | | `--subnet-type ` | Specify the subnet type to create the canister on. If no subnet type is provided, the canister will be created on a random default application subnet. `dfx ledger show-subnet-types` can be used to list available subnet types. | | `--subnet ` | Specify the subnet to create the canister on. If no subnet is provided, the canister will be created on a random default application subnet. | -| `--next-to ` | Create canisters on the same subnet as this canister. | +| `--next-to ` | Create canisters on the same subnet as the specified canister. | ### Arguments @@ -303,8 +291,7 @@ You can use the following argument with the `dfx canister create` command. ### Examples -You can use the `dfx canister create` command to register canister identifiers without first compiling any code. For -example, if you want to create the canister identifier for the project `my_counter` before writing the program, you can +For example, if you want to create the canister identifier for the project `my_counter` before writing the canister code, you can run the following command: ``` bash @@ -321,7 +308,7 @@ dfx canister create --with-cycles 8000000000000 --all #### Allocating message processing -The `--compute-allocation` options allows you to allocate computing resources as a percentage in the range of 0 to 100 +The `--compute-allocation` option 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. For example, assume you run the following command: @@ -330,8 +317,8 @@ For example, assume you run the following command: dfx canister create --all --compute-allocation 50 ``` -With this setting, all of the canisters in the current projects are assigned a 50% allocation. When canisters in the -project receive input messages to process, the messages are scheduled for execution. Over 100 execution cycles, each +With this setting, all of the canisters in the current project are assigned a 50% allocation. When canisters in the +project receive ingress messages to process, the messages are scheduled for execution. Over 100 execution rounds, each canister’s messages will be scheduled for processing at least 50 times. The default value for this option is 0—indicating that no specific allocation or scheduling is in effect. If all of your @@ -339,8 +326,7 @@ canisters use the default setting, processing occurs in a round-robin fashion. ## dfx canister delete -Use the `dfx canister delete` command to delete a stopped canister from the local development environment or the -Internet Computer. By default, this withdraws remaining cycles to your wallet before deleting the canister. +Use the `dfx canister delete` command to delete a stopped canister from the local development environment or the mainnet. By default, this withdraws remaining cycles to your cycles wallet before deleting the canister. Note that you can only run this command from within the project directory structure. For example, if your project name is `hello_world`, your current working directory must be the `hello_world` top-level project directory or one of its @@ -377,15 +363,13 @@ You can use the following arguments with the `dfx canister delete` command. ### Examples -You can use the `dfx canister delete` command to delete a specific canister or all canisters. - To delete the `hello_world` canister, you can run the following command: ``` bash 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 +To delete all of the project's canisters you have deployed on the mainnet and configured in your `dfx.json`, you can run the following command: ``` bash @@ -419,14 +403,12 @@ You can use the following options with the `dfx canister deposit-cycles` command | Option | Description | |----------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `--created-at-time ` | Transaction timestamp, in nanoseconds, for use in controlling transaction deduplication, default is system time. https://internetcomputer.org/docs/current/developer-docs/integrations/icrc-1/#transaction-deduplication- | +| `--created-at-time ` | Transaction timestamp, in nanoseconds, for use in controlling transaction deduplication, default is system time. | | `--from-subaccount ` | Subaccount of the selected identity to spend cycles from. | ### Examples -You can use the `dfx canister deposit-cycles` command to add cycles to a specific canister or all canisters. - To add 1T cycles to the canister called `hello`, you can run the following command: ``` bash @@ -441,20 +423,20 @@ dfx canister deposit-cycles 2000000000000 --all ## dfx canister id -Use the `dfx canister id` command to output the canister identifier/principal for a specific canister name. +Use the `dfx canister id` command to output the canister identifier for a specific canister name. Note that you can only run this command from within the project directory structure. For example, if your project name is `hello_world`, your current working directory must be the `hello_world` top-level project directory or one of its subdirectories. -If the canister has been deployed by the local user, the locally stored canister ID will be provided. +If the canister has been deployed to the local development environment, the locally stored canister ID will be provided. If a canister has been deployed by a third party, the user may set the `.canisters[$CANISTER_NAME].remote[$NETWORK]` entry in `dfx.json` to the canister ID. In this case, the third party is responsible for maintaining the canister and the local user must ensure that they have the correct canister ID. `dfx` will return the provided canister ID with no further checks. -If a canister is typically deployed to the same canister ID on mainnet and all testnets, the user may set a remote +If a canister is typically deployed to the same canister ID on the mainnet, the user may set a remote canister ID for the `__default` network. In this case, `dfx canister id $CANISTER_NAME` will return the default canister ID for all networks that don't have a dedicated entry. @@ -474,8 +456,6 @@ You can use the following argument with the `dfx canister id` command. ### Examples -You can use the `dfx canister id` command to display the canister identifier for a specific canister name. - To display the canister identifier for the `hello_world` canister, you can run the following command: ``` bash @@ -504,13 +484,11 @@ You can use the following argument with the `dfx canister info` command. | Argument | Description | |------------|------------------------------------------------------------------------------| -| `canister` | Specifies the name or id of the canister for which you want to display data. | +| `canister` | Specifies the name or ID of the canister for which you want to display data. | ### Examples -You can use the `dfx canister info` command to display the canister controller and installed Wasm module. - -To the data about the `hello_world` canister, you can run the following command: +To get data about the `hello_world` canister, you can run the following command: ``` bash dfx canister info hello_world @@ -525,8 +503,7 @@ Module hash: 0x2cfb6f216fd6ab367364c02960afbbc5c444f5481225ee676992ac9058fd41e3 ## dfx canister install -Use the `dfx canister install` command to install compiled code as a canister on the Internet Computer or on the local -canister execution environment. +Use the `dfx canister install` command to install compiled code as a canister on the mainnet or the local development environment. ### Basic usage @@ -544,12 +521,12 @@ You can use the following options with the `dfx canister install` command. | `--argument-type ` | Specifies the data type for the argument when making the call using an argument [possible values: idl, raw] | | `--argument-file ` | Specifies the file from which to read the argument to pass to the init method. Stdin may be referred to as `-`. | | `--async-call` | Enables you to continue without waiting for the result of the installation to be returned by polling the Internet Computer or the local development environment. | -| `-m`, `--mode ` | Specifies whether you want to `install`, `reinstall`, or `upgrade` canisters. Defaults to `install`. For more information about installation modes and canister management, see [managing canisters](/docs/current/developer-docs/smart-contracts/maintain/settings). | -| `--no-wallet` | Performs the call with the user Identity as the Sender of messages. Bypasses the Wallet canister. Enabled by default. | +| `-m`, `--mode ` | Specifies whether you want to `install`, `reinstall`, or `upgrade` canisters. Defaults to `install`. For more information about installation modes and canister management, see [managing canisters](https://internetcomputer.org/docs/building-apps/canister-management/settings). | +| `--no-wallet` | Performs the call with the user identity as the sender of messages. Bypasses the wallet canister. Enabled by default. | | `--no-asset-upgrade` | Skips upgrading the asset canister, to only install the assets themselves. | -| `--upgrade-unchanged` | Upgrade the canister even if the .wasm did not change. | -| `--wasm ` | Specifies a particular Wasm file to install, bypassing the dfx.json project settings. | -| `--skip-pre-upgrade` | Skip the pre_upgrade hook on upgrade. This requires the upgrade/auto mode. | +| `--upgrade-unchanged` | Upgrade the canister even if the `.wasm` did not change. | +| `--wasm ` | Specifies a particular Wasm file to install, bypassing the `dfx.json` project settings. | +| `--skip-pre-upgrade` | Skip the `pre_upgrade` hook on upgrade. This requires the upgrade/auto mode. | | `--wasm-memory-persistence ` | Keep or replace the Wasm main memory on upgrade. Possible values: keep, replace. This requires the upgrade/auto mode. | #### Specifies the argument to pass to the init entrypoint @@ -567,8 +544,8 @@ You can use the following arguments with the `dfx canister install` command. ### Examples -You can use the `dfx canister install` command to deploy WebAssembly you have compiled using the `dfx build` command as -a canister on the Internet Computer or on the local development environment. The most common use case is to +You can use the `dfx canister install` command to deploy Wasm you have compiled using the `dfx build` command as +a canister on the mainnet or on the local development environment. The most common use case is to install all of the canisters by running the following command: ``` bash @@ -606,10 +583,10 @@ if you were shipping a package. #### Overriding the default deployment options -If you want to deploy a canister on a testnet without changing the settings in your `dfx.json` configuration file, you -can explicitly specify the testnet you want to connect to by using the `--network` option. +If you want to deploy a canister on a custom local network without changing the settings in your `dfx.json` configuration file, you +can explicitly specify the custom local network you want to connect to by using the `--network` option. -For example, you can specify a testnet URL by running a command similar to the following: +For example, you can specify a custom network URL by running a command similar to the following: ``` bash dfx canister install --all --network http://192.168.3.1:5678 @@ -639,11 +616,11 @@ You can specify the following options for the `dfx canister logs` command. | Option | Description | |-----------------------------|-----------------------------------------------------------------------------------------------------| -| `--follow` | Specifies to fetch logs continuously until interrupted with `Ctrl+C`. | +| `--follow` | Fetches logs continuously until interrupted with `Ctrl+C`. | | `--interval ` | Specifies the interval in seconds between log fetches when following logs. Defaults to 2 seconds. | -| `--since ` | Specifies to show the logs newer than a relative duration, with the valid units `s`, `m`, `h`, `d`. | -| `--since-time ` | Specifies to show the logs newer than a specific timestamp. Required either `nanoseconds` since Unix epoch or `RFC3339` format (e.g. `2021-05-06T19:17:10.000000002Z`). | -| `--tail ` | Specifies to show the last number of the logs. | +| `--since ` | Shows the logs newer than a relative duration, with the valid units `s`, `m`, `h`, `d`. | +| `--since-time ` | Shows the logs newer than a specific timestamp. Required either `nanoseconds` since Unix epoch or `RFC3339` format (e.g. `2021-05-06T19:17:10.000000002Z`). | +| `--tail ` | Shows the last number of the logs. | ### Examples @@ -662,7 +639,7 @@ The command displays output similar to the following: [45. 2021-05-06T19:17:15.000000002Z]: (bytes) 0xc0ffee ``` -To display the latest one log, you can run the following command: +To display the most recent log, you can run the following command: ``` bash dfx canister logs hello_world --tail 1 @@ -718,7 +695,7 @@ dfx canister metadata ### Arguments -You can use the following argument with the `dfx canister metadata` command. +You can use the following arguments with the `dfx canister metadata` command. | Argument | Description | |-----------------|----------------------------------------------------------------------------------| @@ -727,7 +704,7 @@ You can use the following argument with the `dfx canister metadata` command. ### Examples -To display the candid service metadata for the `hello_world` canister, you can run the following command: +To display the Candid service metadata for the `hello_world` canister, you can run the following command: ``` bash dfx canister metadata hello_world candid:service @@ -743,7 +720,7 @@ service : { ## dfx canister request-status -Use the `dfx canister request-status` command to request the status of a specified call to a canister. This command +Use the `dfx canister request-status` command to request the status of a call to a canister. This command requires you to specify the request identifier you received after invoking a method on the canister. The request identifier is an hexadecimal string starting with `0x`. @@ -768,7 +745,7 @@ You can specify the following argument for the `dfx canister request-status` com | Argument | Description | |--------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `request_id` | Specifies the hexadecimal string returned in response to a `dfx canister call` or `dfx canister install` command. This identifier is an hexadecimal string starting with 0x. | -| `canister` | Specifies the name or id of the canister onto which the request was made. If the request was made to the Management canister, specify the id of the canister it is updating/querying. If the call was proxied by the wallet, i.e. a `dfx canister call --async --wallet=` flag, specify the wallet canister id. | +| `canister` | Specifies the name or ID of the canister onto which the request was made. If the request was made to the management canister, specify the ID of the canister it is updating/querying. If the call was proxied by the cycles wallet, i.e. a `dfx canister call --async --wallet=` flag, specify the wallet canister ID. | ### Examples @@ -797,13 +774,6 @@ message. dfx canister send [options] ``` -### Options - -You can use the following options with the `dfx canister request-status` command. - -| Option | Description | -|------------|-----------------------------------------------------| -| `--status` | Send the signed request-status call in the message. | ### Arguments @@ -813,13 +783,6 @@ You can specify the following argument for the `dfx canister send` command. |-------------|-----------------------------------------| | `file_name` | Specifies the file name of the message. | -### Examples - -Use the `dfx canister send` command to send a signed message created using the `dfx canister sign` command to the -genesis token canister (GTC) to create a neuron on your behalf by running the following command: - -`dfx canister send message.json` - ## dfx canister set-id Use the `dfx canister set-id` command to set the canister identifier/principal for a specific canister name. @@ -849,7 +812,7 @@ You can use the following options with the `dfx canister set-id` command. | Option | Description | |-------------|-----------------------------------------------| -| `--network` | The network for which you want to set the id. | +| `--network` | The network for which you want to set the ID. | ### Examples @@ -863,14 +826,15 @@ The command displays output similar to the following: ``` bash Set canister id for hello_backend to qhbym-qaaaa-aaaaa-aaafq-cai +``` ## dfx canister sign Use the `dfx canister sign` command before sending a message with the `dfx canister send` command when you want to -separate these steps, rather than using the single `dfx canister call` command. Using separate calls can add security to -the transaction. For example, when creating your neuron stake, you might want to use the `dfx canister sign` command to +separate these steps rather than using the single `dfx canister call` command. Using separate calls can add security to +the transaction. For example, when creating a neuron stake, you might want to use the `dfx canister sign` command to create a signed `message.json` file using an air-gapped computer, then use the `dfx canister send` command to deliver -the signed message from a computer connected to the Internet Computer. +the signed message from a computer connected to the internet. ### Basic usage @@ -903,9 +867,9 @@ You can specify the following arguments for the `dfx canister sign` command. | `method_name` | Specifies the method name to call on the canister. The canister method is a required argument. | | `argument` | Specifies the argument to pass to the method | -#### Specifies the argument to pass to the method +#### Specify an argument to pass to the method -Depending on your program logic, the argument can be a required or optional argument. You can specify a data format type using the `--type` option if you pass an argument to the canister. By default, you can specify arguments using the [Candid](/docs/current/references/candid-ref) (`idl`) syntax for data values. For information about using Candid and its supported types, see [Interact with a service in a terminal](/docs/current/developer-docs/smart-contracts/candid/candid-howto#idl-syntax) and [supported types](/docs/current/references/candid-ref#supported-types). You can use `raw` as the argument type if you want to pass raw bytes. +Depending on your program logic, an argument can be a required or optional argument. You can specify a data format type using the `--type` option if you pass an argument to the canister. By default, you can specify arguments using the [Candid](https://internetcomputer.org/docs/references/candid-ref) (`idl`) syntax for data values. You can use `raw` as the argument type if you want to pass raw bytes. ### Examples @@ -914,8 +878,8 @@ command similar to the following: `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 +This command illustrates how to create a `message.json` file to create neurons on the mainnet (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. Note that the time allotted to send a signed message is a fixed 5-minute window. The `--expire-after` option enables you @@ -928,11 +892,6 @@ be recognized as valid. If you don’t specify the `--expire-after` option, the default expiration is five minutes. -Send the signed message to the genesis token canister (GTC) to create a neuron on your behalf by running the following -command: - -`dfx canister send message.json` - ## dfx canister snapshot create Use the `dfx canister snapshot create` command to create a snapshot of a stopped canister. @@ -965,7 +924,7 @@ dfx canister snapshot create hello dfx canister start hello ``` -To replace an existing snapshot to save space: +To replace an existing snapshot: ```sh dfx canister stop hello @@ -1057,8 +1016,7 @@ dfx canister snapshot list hello ## dfx canister start -Use the `dfx canister start` command to restart a stopped canister on the Internet Computer or the local canister -execution environment. +Use the `dfx canister start` command to restart a stopped canister on the mainnet or the local development environment. In most cases, you run this command after you have stopped a canister to properly terminate any pending requests as a prerequisite to upgrading the canister. @@ -1084,15 +1042,13 @@ You can use the following arguments with the `dfx canister start` command. ### Examples -You can use the `dfx canister start` command to start a specific canister or all canisters. - To start the `hello_world` canister, you can run the following command: ``` bash 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: +To start all of the canisters you have deployed on the mainnet, you can run the following command: ``` bash dfx canister start --all --network=ic @@ -1101,7 +1057,7 @@ dfx canister start --all --network=ic ## dfx canister status Use the `dfx canister status` command to check whether a canister is currently running, in the process of stopping, or -currently stopped on the Internet Computer or on the local development environment. +currently stopped on the mainnet or the local development environment. Note that you can only run this command from within the project directory structure. For example, if your project name is `hello_world`, your current working directory must be the `hello_world` top-level project directory or one of its @@ -1133,7 +1089,7 @@ To check the status of the `hello_world` canister, you can run the following com 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 +To check the status for all of the canisters within your current project that have deployed on the mainnet, you can run the following command: ``` bash @@ -1142,7 +1098,7 @@ dfx canister status --all --network=ic ## dfx canister stop -Use the `dfx canister stop` command to stop a canister that is currently running on the Internet Computer or on the +Use the `dfx canister stop` command to stop a canister that is currently running on the mainnet or on the local development environment. In most cases, you run this command to properly terminate any pending requests as a prerequisite to upgrading the @@ -1177,7 +1133,7 @@ To stop the `hello_world` canister, you can run the following command: 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: +To stop all of the canisters within your project that you have deployed on the mainnet, you can run the following command: ``` bash dfx canister stop --all --network=ic @@ -1186,9 +1142,9 @@ dfx canister stop --all --network=ic ## dfx canister uninstall-code Use the `dfx canister uninstall-code` command to uninstall the code that a canister that is currently running on the -Internet Computer or on the local development environment. +mainnet or on the local development environment. -This method removes a canister’s code and state, making the canister empty again. Only the controller of the canister +This method removes a canister’s code and state, making the canister empty. Only the controller of the canister can uninstall code. Uninstalling a canister’s code will reject all calls that the canister has not yet responded to, and drop the canister’s code and state. Outstanding responses to the canister will not be processed, even if they arrive after code has been installed again. The canister is now empty. @@ -1214,15 +1170,13 @@ You can use the following arguments with the `dfx canister uninstall-code` comma ### Examples -You can use the `dfx canister uninstall-code` command to uninstall a specific canister or all canisters. - To uninstall the `hello_world` canister, you can run the following command: ``` bash 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: +To uninstall all of the canisters within your project that you have deployed on the mainnet, you can run the following command: ``` bash dfx canister uninstall-code --all --network=ic @@ -1230,8 +1184,7 @@ dfx canister uninstall-code --all --network=ic ## dfx canister update-settings -Use the `dfx canister update-settings` command to update the settings of a canister running in the local execution -environment. +Use the `dfx canister update-settings` command to update the settings of a canister running in the local development environment. In most cases, you run this command to tune the amount of resources allocated to your canister. @@ -1279,8 +1232,6 @@ You can use the following arguments with the `dfx canister update-settings` comm ### Examples -You can use the `dfx canister update-settings` command to update settings of a specific canister. - To update the settings of the `hello_world` canister, you can run the following command: ``` bash @@ -1295,10 +1246,10 @@ Note that you can only run this command from within the project directory struct is `hello_world`, your current working directory must be the `hello_world` top-level project directory or one of its subdirectories. -If the canister has been deployed by the local user, the locally stored canister ID will be provided within the url. +If the canister has been deployed locally, the locally stored canister ID will be provided within the URL. You can check the `.dfx/local/canister_ids.json` file in the project directory for details. -If a canister has been deployed by a third party, the user may set the `.canisters[$CANISTER_NAME].remote[$NETWORK]` +If a canister has been deployed by a third party on the mainnet, the user may set the `.canisters[$CANISTER_NAME].remote[$NETWORK]` entry in `dfx.json` to the canister ID. In this case, the third party is responsible for maintaining the canister and the local user must ensure that they have the correct canister ID. `dfx` will use the provided canister ID with no further checks. @@ -1319,7 +1270,7 @@ You can use the following argument with the `dfx canister url` command. ### Examples -To display the canister url for the `hello_world_backend` canister, you can run the following command: +To display the canister URL for the `hello_world_backend` canister, you can run the following command: ``` bash dfx canister url hello_world_backend @@ -1346,4 +1297,4 @@ The command displays output similar to the following: https://a4gq6-oaaaa-aaaab-qaa4q-cai.raw.icp0.io/?id=bkyz2-fmaaa-aaaaa-qaaaq-cai ``` -The `a4gq6-oaaaa-aaaab-qaa4q-cai` is the canister id for `__Candid_UI` canister on the IC mainnet. +The `a4gq6-oaaaa-aaaab-qaa4q-cai` is the canister id for `__Candid_UI` canister on the mainnet. diff --git a/docs/cli-reference/dfx-completion.mdx b/docs/cli-reference/dfx-completion.mdx index 59704250fe..fc267d3e6b 100644 --- a/docs/cli-reference/dfx-completion.mdx +++ b/docs/cli-reference/dfx-completion.mdx @@ -25,28 +25,30 @@ You can use the following option with the `dfx completion` command. | Option | Description -| |-----------------------|-------------------------------------| -| `--bin-name ` | Name of the command. Only needed if referring to dfx by another name, such as with an alias. Default `dfx`. | +| `--bin-name ` | Name of the command. Only needed if referring to `dfx` by another name, such as with an alias. Default `dfx`. | ## Examples -Generate a bash completion script: +Generate a `bash` completion script: ``` bash dfx completion ``` -Generate a zsh completion script: +Generate a `zsh` completion script: ``` bash dfx completion zsh ``` -Enable completion in zsh: +Enable completion in `zsh`, e.g. by placing this line in `~/.zshrc`: + ```bash source <(dfx completion zsh) ``` -Enable completion in bash: +Enable completion in `bash`, e.g. by placing this line in `~/.bashrc`: + ```bash source <(dfx completion) ``` diff --git a/docs/cli-reference/dfx-config.mdx b/docs/cli-reference/dfx-config.mdx index 32df3a5a42..ebce71103d 100644 --- a/docs/cli-reference/dfx-config.mdx +++ b/docs/cli-reference/dfx-config.mdx @@ -4,7 +4,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -The `dfx config` command reports or modifies DFX's configuration. It can also be modified manually (see `dfx info config-json-path`). +The `dfx config` command reports or modifies `dfx`'s configuration. It can also be modified manually (see `dfx info config-json-path`). Some settings have associated environment variables or CLI flags which will override the file. `dfx config` will emit a warning when you change an overridden setting, and when the settings are queried, will report the setting it actually uses (i.e. post-override). @@ -14,10 +14,10 @@ Some settings have associated environment variables or CLI flags which will over dfx config [value] ``` -When a value is not supplied, dfx will print the current *effective* value of that field. +When a value is not supplied, `dfx` will print the current *effective* value of that field. ## Config fields | Command | Description | |----------------------------|----------------------------------------------------------------------------------------------------------------------------------| -| `telemetry [on|off|local]` | Sets whether telemetry is enabled. `local` means dfx will collect the logs but not transmit them. Overridden by `$DFX_TELEMETRY` | +| `telemetry [on|off|local]` | Sets whether telemetry is enabled. `local` means `dfx` will collect the logs but not transmit them. Overridden by `$DFX_TELEMETRY` | diff --git a/docs/cli-reference/dfx-cycles.mdx b/docs/cli-reference/dfx-cycles.mdx index d9c934727e..ea3c066691 100644 --- a/docs/cli-reference/dfx-cycles.mdx +++ b/docs/cli-reference/dfx-cycles.mdx @@ -4,7 +4,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -Use the `dfx cycles` command to manage cycles associated with an identity's principal. +Use the `dfx cycles` command to manage cycles associated with an identity's principal. `dfx cycles` uses the cycles ledger for cycles management. The basic syntax for running `dfx cycles` commands is: @@ -17,7 +17,7 @@ The following subcommands are available: | Command | Description | |-------------------------------------------------|--------------------------------------------------------------------------------------| | [`approve`](#dfx-cycles-approve) | Approves a principal to spend cycles on your behalf. | -| [`balance`](#dfx-cycles-balance) | Prints the account balance of the user. | +| [`balance`](#dfx-cycles-balance) | Prints the account balance of the current principal. | | [`convert`](#dfx-cycles-convert) | Convert some of the user's ICP balance into cycles. | | [`redeem-faucet-coupon`](#redeem-faucet-coupon) | Redeem a code at the cycles faucet. | | [`top-up`](#dfx-cycles-top-up) | Deposit cycles into a canister. | @@ -53,12 +53,12 @@ You can specify the following options for the `dfx cycles approve` command. | Option | Description | |-------------------------------------|----------------------------------------------------------------------------------------| -| `--created-at-time ` | Specify the timestamp-nanoseconds for the `created_at_time` field on the transfer request. Useful for controlling [transaction-de-duplication](https://internetcomputer.org/docs/current/developer-docs/integrations/icrc-1/#transaction-deduplication-). | +| `--created-at-time ` | Specify the timestamp-nanoseconds for the `created_at_time` field on the transfer request. Useful for controlling transaction-de-duplication. | | `--expected-allowance ` | The number of previously approved cycles. See [ICRC-2 specification](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md) for details. | | `--expires-at ` | Timestamp-nanoseconds until which the approval is valid. None means that the approval is valid indefinitely. | -| `--from-subaccount ` | Approve cycles to be spent from this subaccount. | +| `--from-subaccount ` | Approve cycles to be spent from the specified subaccount. | | `--memo ` | Specifies a numeric memo for this transaction. | -| `--spender-subaccount ` | Allow this subaccount to spend cycles. | +| `--spender-subaccount ` | Allow the specified subaccount to spend cycles. | ### Examples @@ -90,8 +90,8 @@ You can specify the following arguments for the `dfx cycles balance` command. | Option | Description | |---------------------------------------------|---------------------------------------------------------------------| -| `--owner ` | Display the balance of this principal | -| `--subaccount ` | Display the balance of this subaccount | +| `--owner ` | Display the balance of the specified principal. | +| `--subaccount ` | Display the balance of the specified subaccount. | | `--precise` | Displays the exact balance, without scaling to trillions of cycles. | ### Examples @@ -104,6 +104,7 @@ $ dfx cycles balance --network ic ``` To see the exact amount of cycles, you can use the `--precise` option: + ``` $ dfx cycles balance --network ic --precise 89000000000000 cycles. @@ -132,8 +133,8 @@ You can specify the following arguments for the `dfx cycles convert` command. | Option | Description | |---------------------------------------------|-------------| | `--amount ` | Specify the number of ICP tokens to convert to cycles and deposit into your cycles ledger account. You can specify an amount as a number with up to eight (8) decimal places. | -| `--created-at-time `| Specify the timestamp-nanoseconds for the `created_at_time` field on the ledger transfer request. Useful for transaction deduplication. https://internetcomputer.org/docs/current/developer-docs/integrations/icrc-1/#transaction-deduplication- | -| `--e8s ` | Specify ICP token fractional units—called e8s—as a whole number, where one e8 is the smallest fraction of an ICP token. For example, 1.05000000 is 1 ICP and 5000000 e8s. You can use this option on its own or in conjunction with the `--icp` option. | +| `--created-at-time `| Specify the timestamp-nanoseconds for the `created_at_time` field on the ledger transfer request. Useful for transaction deduplication. | +| `--e8s ` | Specify ICP token fractional units (called e8s) as a whole number, where one e8 is the smallest fraction of an ICP token. For example, 1.05000000 is 1 ICP and 5000000 e8s. You can use this option on its own or in conjunction with the `--icp` option. | | `--fee ` | Specify a transaction fee. The default is 10000 e8s. | | `--icp ` | Specify ICP tokens as a whole number. You can use this option on its own or in conjunction with `--e8s`. | | `--deposit-memo ` | Memo used when depositing the minted cycles. | @@ -141,7 +142,7 @@ You can specify the following arguments for the `dfx cycles convert` command. ### Examples -Convert 10 ICP into cycles. +Convert 10 ICP into cycles: ``` $ dfx cycles convert --network ic --amount 10 @@ -180,12 +181,12 @@ You can specify the following options for the `dfx cycles transfer` command. | Option | Description | |-------------------------------------|----------------------------------------------------------------------------------------| -| `--from ` | Transfer cycles from this principal. Requires that principal's approval. | +| `--from ` | Transfer cycles from the specified principal. Requires that principal's approval. | | `--to-subaccount ` | The subaccount to which you want to transfer cycles. | | `--from-subaccount ` | The subaccount from which you want to transfer cycles. | | `--spender-subaccount ` | Deduct allowance from this subaccount. Requires `--from` to be specified. | | `--memo ` | Specifies a numeric memo for this transaction. | -| `--created-at-time ` | Specify the timestamp-nanoseconds for the `created_at_time` field on the transfer request. Useful for controlling transaction-de-duplication. https://internetcomputer.org/docs/current/developer-docs/integrations/icrc-1/#transaction-deduplication- | +| `--created-at-time ` | Specify the timestamp-nanoseconds for the `created_at_time` field on the transfer request. Useful for controlling transaction-de-duplication. | ### Examples @@ -238,7 +239,7 @@ If you have a coupon code `ABCDE-ABCDE-ABCDE`, you can redeem it like this: dfx cycles redeem-faucet-coupon 'ABCDE-ABCDE-ABCDE' ``` -This will print something similar to this: +This will print something like: ``` Redeemed coupon ABCDE-ABCDE-ABCDE to the cycles ledger for 10 TC (trillion cycles). New balance: 10 TC. ``` @@ -259,7 +260,7 @@ You must specify the following arguments for the `dfx cycles transfer` command. | Argument | Description | |------------|-------------------------------------------------------------------------| -| `` | The name of a canister in the current project, or a canister principal. | +| `` | The name of a canister in the current project or a canister principal. | | `` | The number of cycles to transfer. | ### Options @@ -269,7 +270,7 @@ You can specify the following options for the `dfx cycles top-up` command. | Option | Description | |----------------------------------|----------------------------------------------------------------------------------------| | `--from-subaccount ` | The subaccount from which you want to transfer cycles. | -| `--created-at-time ` | Specify the timestamp-nanoseconds for the `created_at_time` field on the transfer request. Useful for controlling transaction deduplication. https://internetcomputer.org/docs/current/developer-docs/integrations/icrc-1/#transaction-deduplication- | +| `--created-at-time ` | Specify the timestamp-nanoseconds for the `created_at_time` field on the transfer request. Useful for controlling transaction deduplication.| ### Examples diff --git a/docs/cli-reference/dfx-deploy.mdx b/docs/cli-reference/dfx-deploy.mdx index 27a3917631..5f433fb625 100644 --- a/docs/cli-reference/dfx-deploy.mdx +++ b/docs/cli-reference/dfx-deploy.mdx @@ -4,7 +4,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -Use the `dfx deploy` command to register, build, and deploy a dapp on the local development environment, on the IC or on a specified testnet. By default, all canisters defined in the project `dfx.json` configuration file are deployed. +Use the `dfx deploy` command to register, build, and deploy a dapp on the local development environment, on the mainnet or on a specified local network. By default, all canisters defined in the project `dfx.json` configuration file are deployed. This command simplifies the developer workflow by enabling you to run one command instead of running the following commands as separate steps: @@ -29,27 +29,27 @@ You can use the following options with the `dfx deploy` command. | Option | Description | |------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `--network ` | Overrides the environment to connect to. By default, the local development environment is used. | -| `--playground ` | Alias for `--network playground`. By default, canisters on this network are borrowed from the Motoko Playground. | +| `--playground ` | Alias for `--network playground`. | | `--ic ` | Alias for `--network ic`. | | `--argument ` | Specifies an argument to pass to the canister during installation. | | `--argument-type ` | Specifies the data type for the argument when making the call using an argument [possible values: idl, raw] | | `--argument-file ` | Specifies the file from which to read the argument to pass to the init method. Stdin may be referred to as `-`. | -| `--created-at-time ` | Transaction timestamp, in nanoseconds, for use in controlling transaction deduplication, default is system time. https://internetcomputer.org/docs/current/developer-docs/integrations/icrc-1/#transaction-deduplication- | +| `--created-at-time ` | Transaction timestamp, in nanoseconds, for use in controlling transaction deduplication, default is system time. | | `--from-subaccount ` | Subaccount of the selected identity to spend cycles from. | -| `-m`, `--mode ` | Specifies whether you want to `install`, `reinstall`, or `upgrade` canisters. Defaults to `auto`. For more information about installation modes and canister management, see [managing canisters](/docs/current/developer-docs/smart-contracts/maintain/settings). | +| `-m`, `--mode ` | Specifies whether you want to `install`, `reinstall`, or `upgrade` canisters. Defaults to `auto`. For more information about installation modes and canister management, see [managing canisters](https://internetcomputer.org/docs/building-apps/canister-management/settings). | | `--with-cycles ` | Enables you to specify the initial number of cycles for a canister in a project. | -| `--specified-id ` | Attempts to create the canister with this Canister ID | -| `--by-proposal` | Upload proposed changed assets, but do not commit them. Follow up by calling either commit_proposed_batch() or delete_batch(). | +| `--specified-id ` | Attempts to create the canister with this canister ID | +| `--by-proposal` | Upload proposed changed assets, but do not commit them. Follow up by calling either `commit_proposed_batch()` or `delete_batch()`. | | `--compute-evidence` | Build a frontend canister, determine batch operations required to synchronize asset canister contents, and compute a hash over those operations. Displays this hash ("evidence"), which should match the evidence displayed by `dfx deploy --by-proposal`. | | `--subnet-type ` | Specify the subnet type to create the canister on. If no subnet type is provided, the canister will be created on a random default application subnet. `dfx ledger show-subnet-types` can be used to list available subnet types. | | `--subnet ` | Specify the subnet to create the canister on. If no subnet is provided, the canister will be created on a random default application subnet. | | `--next-to ` | Create canisters on the same subnet as this canister. | -| `--skip-pre-upgrade` | Skip the pre_upgrade hook on upgrade. This requires the upgrade/auto mode. | +| `--skip-pre-upgrade` | Skip the `pre_upgrade` hook on upgrade. This requires the upgrade/auto mode. | | `--wasm-memory-persistence ` | Keep or replace the Wasm main memory on upgrade. Possible values: keep, replace. This requires the upgrade/auto mode. | ### Specifies the argument to pass to the init entrypoint -With `--argument-type`, you can specify the data format for the argument when you install using the `--argument` option. The valid values are `idl` and `raw`. By default, you can specify arguments using the [Candid](/docs/current/developer-docs/smart-contracts/candid/candid-concepts) (`idl`) syntax for data values. For information about using Candid and its supported types, see [Interact with a service in a terminal](/docs/current/developer-docs/smart-contracts/candid/candid-howto#idl-syntax) and [Supported types](/docs/current/references/candid-ref). You can use `raw` as the argument type if you want to pass raw bytes to a canister. +With `--argument-type`, you can specify the data format for the argument when you install using the `--argument` option. The valid values are `idl` and `raw`. By default, you can specify arguments using the [Candid](https://internetcomputer.org/docs/references/candid-ref) (`idl`) syntax for data values. You can use `raw` as the argument type if you want to pass raw bytes to a canister. ## Arguments @@ -61,9 +61,7 @@ You can specify the following arguments for the `dfx deploy` command. ## Examples -You can use the `dfx deploy` command to deploy all or specific canisters on the local development environment, on the IC or on a specified testnet. - -For example, to deploy the `hello` project on the hypothetical `ic-pubs` testnet configured in the `dfx.json` configuration file, you can run the following command: +For example, to deploy the `hello` project on the hypothetical `ic-pubs` local network configured in the `dfx.json` configuration file, you can run the following command: ``` bash dfx deploy hello_backend --network ic-pubs @@ -75,14 +73,7 @@ To deploy a project on the local development environment and pass a single argum dfx deploy hello_actor_class --argument '("from DFINITY")' ``` -Note that currently you must use an actor class in your Motoko dapp. In this example, the `dfx deploy` command specifies an argument to pass to the `hello_actor_class` canister. The main program for the `hello_actor_class` canister looks like this: -```motoko -actor class Greet(name: Text) { - public query func greet() : async Text { - return "Hello, " # name # "!"; - }; -}; -``` +In this example, the `dfx deploy` command specifies an argument to pass to the `hello_actor_class` canister. You can use the `dfx deploy` command with the `--with-cycles` option to specify the initial balance of a canister created by your wallet. If you don’t specify a canister, the number of cycles you specify will be added to all canisters by default. To avoid this, specify a specific canister by name. For example, to add an initial balance of 8000000000000 cycles to a canister called "hello-assets", run the following command: diff --git a/docs/cli-reference/dfx-deps.mdx b/docs/cli-reference/dfx-deps.mdx index 0876e0cc74..427af8f603 100644 --- a/docs/cli-reference/dfx-deps.mdx +++ b/docs/cli-reference/dfx-deps.mdx @@ -6,7 +6,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; Use the `dfx deps` command with flags and subcommands to pull dependencies from the mainnet and deploy locally. -[Learn how to configure a canister as `pullable`](https://internetcomputer.org/docs/current/developer-docs/smart-contracts/maintain/import). +[Learn how to configure a canister as `pullable`](https://internetcomputer.org/docs/building-apps/advanced/using-third-party-canisters). The basic syntax for running `dfx deps` commands is: @@ -30,7 +30,7 @@ dfx deps pull --help ## dfx deps pull -Use the `dfx deps pull` command to pull dependencies as defined in `dfx.json`. +Use the `dfx deps pull` command to pull dependencies as defined in `dfx.json`. It will resolve all transitive dependencies. ### Basic usage @@ -40,7 +40,7 @@ dfx deps pull [options] ### Arguments -You can specify the following argument for the `dfx deps delete` command. +You can specify the following argument for the `dfx deps pull` command. | Command | Description | | --------- | --------------------------------------------------------------- | @@ -48,12 +48,6 @@ You can specify the following argument for the `dfx deps delete` command. ### Examples -You can use the `dfx deps pull` command to pull the dependencies as defined in `dfx.json` from the mainnet. It will resolve all indirect dependencies. - -``` bash -dfx deps pull -``` - For testing, you may want to pull from local environment, then run: ```bash @@ -72,19 +66,13 @@ dfx deps init [options] [canister] ### Examples -You can use the `dfx deps init` command to set empty init arguments for all pulled dependencies. - -``` bash -dfx deps init -``` - If any of the dependencies require init arguments, the above command will alarm you with their canister ID and names if exist. Then you can specify canister ID or name to set init argument for individual dependency. ```bash -`dfx deps init --argument [--argument-type ]` +dfx deps init --argument [--argument-type ] ``` -The command below set number `1` for canister `dep_a` as the argument type is the default `idl` (candid). +The command below set number `1` for canister `dep_a` as the argument type is the default `idl` (Candid). ```bash dfx deps init dep_a --argument 1 @@ -114,8 +102,6 @@ dfx deps deploy [flag] ### Examples -You can use the `dfx deps deploy` command to deploy dependencies to the local environment. - ``` bash dfx deps deploy ``` diff --git a/docs/cli-reference/dfx-envars.mdx b/docs/cli-reference/dfx-envars.mdx index 8fefbbd72a..2e6b1bda4d 100644 --- a/docs/cli-reference/dfx-envars.mdx +++ b/docs/cli-reference/dfx-envars.mdx @@ -4,9 +4,9 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -You can configure certain properties for your SDK execution environment using environment variables. +You can configure certain properties for your local development environment using environment variables. -This section lists the environment variables that are currently supported with examples of how to use them. In most cases, you can set environment variables for a session by executing an command in the terminal or by adding a line similar to the following to your `.profile` file: +This section lists the environment variables that are currently supported with examples of how to use them. In most cases, you can set environment variables for a session by executing a command in the terminal or by adding a line similar to the following to your `.profile` file: ```shell export DFX_NETWORK=ic @@ -18,11 +18,13 @@ Use environment variables with the `CANISTER_CANDID_PATH` prefix to reference th For example, if you have a `whoami_frontend` canister that lists `whoami` under the `dependencies` key, you could use the `CANISTER_CANDID_PATH_whoami_frontend` environment variable to refer to the location of the `whoami.did` file, which for local development might be: - $PROJECT_ROOT/.dfx/local/canisters/whoami/whoami.did +``` +$PROJECT_ROOT/.dfx/local/canisters/whoami/whoami.did +``` ## CANISTER_ID\_\{canister.name\} -Use environment variables with the `CANISTER_ID` prefix to reference the canister identifier for each canister in the `dfx.json` file for your project. Hyphens are invalid in environment variables and are replaced by underscores. Lowercase characters are replaced by uppercase characters. +Use environment variables with the `CANISTER_ID` prefix to reference the canister identifier for each canister in the `dfx.json` file for your project. Hyphens are invalid in environment variables and are replaced by underscores. Lowercase characters are replaced by uppercase characters. For example, if you have a `linkedup` project that consists of the `linkedup` and `connect-d` canisters, you could use the `CANISTER_ID_LINKEDUP` and `CANISTER_ID_CONNECT_D` environment variables to refer to the canister identifiers—for example `ryjl3-tyaaa-aaaaa-aaaba-cai` and `rrkah-fqaaa-aaaaa-aaaaq-cai`—created for your project. @@ -32,13 +34,15 @@ Use the `DFX_CONFIG_ROOT` environment variable to specify a different location f By default, the `.cache` and `.config` directories are located in the home directory for your development environment. For example, on macOS the default location is in the `/Users/` directory. Use the `DFX_CONFIG_ROOT` environment variable to specify a different location for these directories. - DFX_CONFIG_ROOT=~/ic-root +``` +DFX_CONFIG_ROOT=~/ic-root +``` ## DFX_INSTALLATION_ROOT Use the `DFX_INSTALLATION_ROOT` environment variable to specify a different location for the `dfx` binary if you are not using the default location for your operating system. -The `.cache/dfinity/uninstall.sh` script uses this environment variable to identify the root directory for your SDK installation. +The `.cache/dfinity/uninstall.sh` script uses this environment variable to identify the root directory for your `dfx` installation. ## DFX_NETWORK @@ -49,17 +53,19 @@ If you pass the `--network` option to a `dfx` command, the value of the `DFX_NET Use the `DFX_VERSION` environment variable to identify a specific version of the SDK that you want to install. - DFX_VERSION=0.10.0 sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)" +``` +DFX_VERSION=0.10.0 sh -ci "$(curl -fsSL https://internetcomputer.org/install.sh)" +``` ## DFX_MOC_PATH -Use the `DFX_MOC_PATH` environment variable to use a different version of the Motoko compiler than the one bundled with a given dfx version. +Use the `DFX_MOC_PATH` environment variable to use a different version of the Motoko compiler than the one bundled with a given `dfx` version. ## DFX_WARNING -Use the `DFX_WARNING` environment variable to disable one or more warnings that dfx may display. The value is a comma-separated list of warning names, each prefixed with a "-" to disable. The following warning names are currently supported: +Use the `DFX_WARNING` environment variable to disable one or more warnings that `dfx` may display. The value is a comma-separated list of warning names, each prefixed with a "-" to disable. The following warning name is currently supported: -- `mainnet_plaintext_identity`: Disables the warning message that is displayed when you use an insecure identity on the Internet Computer mainnet. +- `mainnet_plaintext_identity`: Disables the warning message that is displayed when you use an insecure identity on the mainnet. ```bash export DFX_WARNING="-mainnet_plaintext_identity" diff --git a/docs/cli-reference/dfx-generate.mdx b/docs/cli-reference/dfx-generate.mdx index ee4374d456..af31fff5f3 100644 --- a/docs/cli-reference/dfx-generate.mdx +++ b/docs/cli-reference/dfx-generate.mdx @@ -6,7 +6,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; Use the `dfx generate` command to generate canister type declarations for supported programming languages. Currently, `dfx generate` supports four languages: Motoko, Candid, JavaScript, and TypeScript. -You can use this command to generate type declarations for all canisters that are defined for a project in the project’s `dfx.json` configuration file or a specific canister. +You can use this command to generate type declarations for all canisters that are defined in the project’s `dfx.json` configuration file or for a specific canister. Note that you can only run this command from within the project directory structure. For example, if your project name is `hello_world`, your current working directory must be the `hello_world` top-level project directory or one of its subdirectories. @@ -47,7 +47,7 @@ Outputs from `dfx generate`: ## Examples -Note that the file name and path to the programs on your file system must match the information specified in the `dfx.json` configuration file. +Note that the file name and path to the canisters on your file system must match the information specified in the `dfx.json` configuration file. In this example, the `hello_world` canister itself is written in Motoko. The `declarations` section specifies that type declarations for all four languages will be generated and stored at `src/declarations/`. @@ -55,7 +55,7 @@ In this example, the `hello_world` canister itself is written in Motoko. The `de dfx generate hello_world ``` -Since there is only one canister in `dfx.json`, calling `dfx generate` without an argument will have the same effect as the above command. If there were multiple canisters defined in `dfx.json`, this would generate type declarations for all defined canisters. +If there is only one canister in `dfx.json`, calling `dfx generate` without an argument will have the same effect as the above command. If there were multiple canisters defined in `dfx.json`, this would generate type declarations for all defined canisters. ``` bash dfx generate diff --git a/docs/cli-reference/dfx-identity.mdx b/docs/cli-reference/dfx-identity.mdx index 420b2e4b0b..12bdce8efd 100644 --- a/docs/cli-reference/dfx-identity.mdx +++ b/docs/cli-reference/dfx-identity.mdx @@ -4,7 +4,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -Use the `dfx identity` command with subcommands and flags to manage the identities used to execute commands and communicate with the IC or the local development environment. Creating multiple user identities enables you to test user-based access controls. +Use the `dfx identity` command with subcommands and flags to manage the identities used to execute commands and communicate with the mainnet or the local development environment. Creating multiple user identities enables you to test user-based access controls. The basic syntax for running `dfx identity` commands is: @@ -22,7 +22,7 @@ For reference information and examples that illustrate using `dfx identity` comm | Command | Description | |-------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------| -| [`deploy-wallet`](#dfx-identity-deploy-wallet) | Installs the wallet Wasm to the provided canister id. | +| [`deploy-wallet`](#dfx-identity-deploy-wallet) | Installs the cycles wallet Wasm to the provided canister id. | | [`get-principal`](#dfx-identity-get-principal) | Shows the textual representation of the principal associated with the current identity. | | [`get-wallet`](#dfx-identity-get-wallet) | Shows the canister identifier for the wallet associated with your current identity principal. | | `help` | Displays this usage message or the help of the given subcommand(s). | @@ -42,15 +42,17 @@ The first time you run the `dfx canister create` command to register an identifi You can then use `dfx identity new` to create new user identities and store credentials for those identities in `$HOME/.config/dfx/identity//identity.pem` files. For example, you can create an identity named `ic_admin` by running the following command: - dfx identity new ic_admin +``` +dfx identity new ic_admin +``` This command adds a private key for the `ic_admin` user identity in the `~/.config/dfx/identity/ic_admin/identity.pem` file. ## dfx identity deploy-wallet -Use the `dfx identity deploy-wallet` command to turn a canister into a wallet canister by installing the wallet Wasm to it. +Use the `dfx identity deploy-wallet` command to turn a canister into a cycles wallet canister by installing the cycles wallet Wasm to it. -Note that you must be connected to the IC or the local development environment to run this command. In addition, you must be a controller of the canister you want to deploy the wallet to. +Note that you must be connected to the mainnet or the local development environment to run this command. In addition, you must be a controller of the canister you want to deploy the wallet to. ### Basic usage @@ -64,7 +66,7 @@ You must specify the following argument for the `dfx identity deploy-wallet` com | Argument | Description | |-----------------|----------------------------------------------------------------| -| `` | The ID of the canister where the wallet Wasm will be deployed. | +| `` | The ID of the canister where the cycles wallet Wasm will be deployed. | ## dfx identity get-principal @@ -93,7 +95,7 @@ In this example, the first command sets the user context to use the `ic_admin` i Use the `dfx identity get-wallet` command to display the canister identifier for the wallet associated with your current identity principal. -Note that you must be connected to the IC or the local development environment to run this command. In addition, you must be in a project directory to run the command. For example, if your project name is `hello_world`, your current working directory must be the `hello_world` top-level project directory or one of its subdirectories to run the `dfx identity get-wallet` command. +Note that you must be connected to the mainnet or the local development environment to run this command. In addition, you must be in a project directory to run the command. For example, if your project name is `hello_world`, your current working directory must be the `hello_world` top-level project directory or one of its subdirectories to run the `dfx identity get-wallet` command. ### Basic usage @@ -109,7 +111,7 @@ If you want to display the canister identifier for the wallet canister associate 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: +To display the canister identifier for the wallet canister associated with your identity on a specific local network, you might run a command similar to the following: ``` bash dfx identity get-wallet --network=https://192.168.74.4 @@ -138,8 +140,7 @@ dfx identity export alice >generated-id.pem Use the `dfx identity import` command to create a user identity by importing the user’s key information or security certificate from a PEM file or seed phrase file. -*Password policy*: If an identity is imported using `--storage-mode password-protected`, the following requirements apply to the password: -- The password needs to be longer than 8 characters. +If an identity is imported using `--storage-mode password-protected`, the password needs to be longer than 8 characters. ### Basic usage @@ -201,8 +202,7 @@ In this example, the `bob_standard` identity is the currently-active user contex Use the `dfx identity new` command to add new user identities. You should note that the identities you add are global. They are not confined to a specific project context. Therefore, you can use any identity you add using the `dfx identity new` command in any project. Only the characters `ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz.-_@0123456789` are valid in identity names. -*Password policy*: If an identity is created using `--storage-mode password-protected`, the following requirements apply to the password: -- The password needs to be longer than 8 characters. +If an identity is created using `--storage-mode password-protected`, the password needs to be longer than 8 characters. ### Basic usage @@ -220,7 +220,7 @@ You must specify the following argument for the `dfx identity new` command. ### Options -You can specify the following options for the `+dfx identity new+` command. +You can specify the following options for the `dfx identity new` command. |Argument|Description| |--------|-----------| @@ -233,14 +233,18 @@ You can specify the following options for the `+dfx identity new+` command. You can then use `dfx identity new` to create new user identities and store credentials for those identities in `$HOME/.config/dfx/identity//identity.pem` files. For example, you can create an identity named `ic_admin` by running the following command: - dfx identity new ic_admin +``` +dfx identity new ic_admin +``` This command adds a private key for the `ic_admin` user identity in the `~/.config/dfx/identity/ic_admin/identity.pem` file. After adding the private key for the new identity, the command displays confirmation that the identity has been created: - Creating identity: "ic_admin". - Created identity: "ic_admin". +``` +Creating identity: "ic_admin". +Created identity: "ic_admin". +``` ## dfx identity remove @@ -272,22 +276,30 @@ You must specify the following argument for the `dfx identity remove` command. You can use the `dfx identity remove` command to remove any previously-created identity, including the `default` user identity. For example, if you have added named user identities and want to remove the `default` user identity, you can run the following command: - dfx identity remove default +``` +dfx identity remove default +``` The command displays confirmation that the identity has been removed: - Removing identity "default". - Removed identity "default". +``` +Removing identity "default". +Removed identity "default". +``` Although you can delete the `default` identity if you have created other identities to replace it, you must always have at least one identity available. If you attempt to remove the last remaining user context, the `dfx identity remove` command displays an error similar to the following: - Identity error: - Cannot delete the default identity +``` +Identity error: + Cannot delete the default identity +``` If you have an identity with one or more wallets configured, it will only be deleted if you call it with `--drop-wallets`. This is made so that users don't accidentally lose access to their cycles wallets. If you try to delete an identity with at least one wallet configured, it will display the attached wallets like this: - This identity is connected to the following wallets: - identity 'mainnet' on network 'ic' has wallet rwlgt-iiaaa-aaaaa-aaaaa-cai +``` +This identity is connected to the following wallets: + identity 'mainnet' on network 'ic' has wallet rwlgt-iiaaa-aaaaa-aaaaa-cai +``` ## dfx identity rename @@ -312,7 +324,9 @@ You must specify the following arguments for the `dfx identity rename` command. You can rename the `default` user or any identity you have previously created using the `dfx identity rename` command. For example, if you want to rename a `test_admin` identity that you previously created, you would specify the current identity name you want to change **from** and the new name you want to change **to** by running a command similar to the following: - dfx identity rename test_admin devops +``` +dfx identity rename test_admin devops +``` ## dfx identity set-wallet @@ -330,7 +344,7 @@ You can use the following optional flags with the `dfx identity set-wallet` comm | Flag | Description | |-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `--force` | Skips verification that the canister you specify is a valid wallet canister. This option is only useful if you are connecting to the IC running locally. | +| `--force` | Skips verification that the canister is a valid wallet canister. This option is only useful if you are connecting to the local development environment. | ### Example @@ -348,9 +362,9 @@ dfx identity set-wallet --canister-name ${WALLET_CANISTER_ID} --network=https:// Use the `dfx identity use` command to specify the user identity you want to active. You should note that the identities you have available to use are global. They are not confined to a specific project context. Therefore, you can use any identity you have previously created in any project. The identity used by a command is: -- the identity specified in the command with `--identity `, if defined -- else the identity specified by the environment variable `export DFX_IDENTITY=`, if defined -- the identity specified by `dfx identity use `. +- The identity specified in the command with `--identity `, if defined. +- The identity specified by the environment variable `export DFX_IDENTITY=`, if defined. +- The identity specified by `dfx identity use `. ### Basic usage @@ -370,7 +384,9 @@ You must specify the following argument for the `dfx identity use` command. If you want to run multiple commands with the same user identity context, you can run a command similar to the following: - dfx identity use ops +``` +dfx identity use ops +``` After running this command, subsequent commands use the credentials and access controls associated with the `ops` user. @@ -392,6 +408,4 @@ If you want to display the name of the currently-active user identity, you can r dfx identity whoami ``` -The command displays the name of the user identity. For example, you had previously run the command `dfx identity use bob_standard`, the command would display: - - bob_standard +The command displays the name of the user identity. diff --git a/docs/cli-reference/dfx-info.mdx b/docs/cli-reference/dfx-info.mdx index 1b4adbef0c..9b034c78b4 100644 --- a/docs/cli-reference/dfx-info.mdx +++ b/docs/cli-reference/dfx-info.mdx @@ -10,14 +10,14 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; dfx info [type] [flag] ``` -## Information Types +## Information types These are the types of information that the `dfx info` command can display. | Information | Description | |-------------------------------|----------------------------------------------------------------------------------------------------------------------| | candid-ui-url | The URL of the Candid UI canister. | -| config-json-path | Path to DFX configuration `config.json`. | +| config-json-path | Path to `dfx` configuration `config.json`. | | networks-json-path | Path to network definition file `networks.json`. | | default-effective-canister-id | The effective canister ID that dfx will use for management canister calls that don't imply one. | | replica-port | The listening port of the replica. | diff --git a/docs/cli-reference/dfx-killall.mdx b/docs/cli-reference/dfx-killall.mdx index 527046cdfc..9d519b1663 100644 --- a/docs/cli-reference/dfx-killall.mdx +++ b/docs/cli-reference/dfx-killall.mdx @@ -4,7 +4,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -Use the `dfx killall` command to forcibly kill every DFX-related process. +Use the `dfx killall` command to forcibly kill all `dfx`-related process. ## Basic usage @@ -20,4 +20,4 @@ You can kill a stuck process that is not responding to `dfx stop` with this comm dfx killall ``` -This may impact IDE plugins, including from other versions of DFX. For ordinary usage `dfx stop` should be preferred. +This may impact IDE plugins, including from other versions of `dfx`. For ordinary usage `dfx stop` should be preferred. diff --git a/docs/cli-reference/dfx-ledger.mdx b/docs/cli-reference/dfx-ledger.mdx index 69f19fe1c2..b10a4ba8fb 100644 --- a/docs/cli-reference/dfx-ledger.mdx +++ b/docs/cli-reference/dfx-ledger.mdx @@ -4,9 +4,9 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -Use the `dfx ledger` command to interact with the ledger canister. +Use the `dfx ledger` command to interact with the ICP token's ledger canister. -This command can be used to make ICP utility token transactions from one canister to another, or top up canisters with cycles from ICP. +This command can be used to make ICP utility token transactions from one canister to another, or top-up canisters with cycles from converting ICP. The basic syntax for running `dfx ledger` commands is: @@ -18,16 +18,16 @@ Depending on the `dfx ledger` subcommand you specify, additional arguments, opti | Command | Description | |---------------------------------------|--------------------------------------------------------------------------------------| -| [`account-id`](#dfx-ledger-account-id) | Prints the selected identity’s Account Identifier. | +| [`account-id`](#dfx-ledger-account-id) | Prints the selected identity’s account identifier. | | [`approve`](#dfx-ledger-approve) | Approve a principal to spend ICP on your behalf. | | [`balance`](#dfx-ledger-balance) | Prints the account balance of the user. | | [`create-canister`](#dfx-ledger-create-canister) | Creates a canister from ICP. | -| [`fabricate-cycles`](#dfx-ledger-fabricate-cycles) | Local development only: Fabricate cycles out of thin air and deposit them into the specified canister(s) | +| [`fabricate-cycles`](#dfx-ledger-fabricate-cycles) | Local development only: Fabricate cycles out of thin air and deposit them into the specified canister(s). | | `help` | Displays usage information message for a specified subcommand. | | [`notify`](#dfx-ledger-notify) | Notifies the ledger when there is a send transaction to the cycles minting canister. | | [`top-up`](#dfx-ledger-top-up) | Tops up a canister with cycles minted from ICP. | -| [`transfer`](#dfx-ledger-transfer) | Transfers ICP from the user to the destination Account Identifier or principal. | -| [`transfer-from`](#dfx-ledger-transfer-from) | Transfer ICP from the approver princiapl to another principal. | +| [`transfer`](#dfx-ledger-transfer) | Transfers ICP from the user to the destination account identifier or principal. | +| [`transfer-from`](#dfx-ledger-transfer-from) | Transfer ICP from the approver principal to another principal. | To view usage information for a specific subcommand, specify the subcommand and the `--help` flag. For example, to see usage information for `dfx ledger transfer`, you can run the following command: @@ -51,9 +51,9 @@ You can use the following optional flags with the `dfx ledger account-id` comman |------------------------------|--------------------------------------------------------| | `-h`, `--help` | Displays usage information. | | `-V`, `--version` | Displays version information. | -| `--of-canister ` | Alias or principal of the canister controlling the account | -| `--of-principal ` | Principal controlling the account | -| `--subaccount ` | Subaccount identifier (64 character long hex string) | +| `--of-canister ` | Alias or principal of the canister controlling the account. | +| `--of-principal ` | Principal controlling the account. | +| `--subaccount ` | Subaccount identifier (64 character long hex string). | | `--subaccount-of-principal ` | Principal from which the subaccount identifier is derived. | ### Examples @@ -72,7 +72,9 @@ dfx ledger account-id --of-canister qvhpv-4qaaa-aaaaa-aaagq-cai --subaccount-fro The commands display output similar to the following: - 03e3d86f29a069c6f2c5c48e01bc084e4ea18ad02b0eec8fccadf4487183c223 +``` +03e3d86f29a069c6f2c5c48e01bc084e4ea18ad02b0eec8fccadf4487183c223 +``` ## dfx ledger approve @@ -91,7 +93,7 @@ You must specify the following arguments for the `dfx ledger approve` command. | Argument | Description | |---------------------|---------------------------------------| | `` | Allow this principal to spend ICP. | -| `--amount ` | The number of ICPs to approve. Can be specified as a Decimal with the fractional portion up to 8 decimal places i.e. 100.012. | +| `--amount ` | The number of ICPs to approve. Can be specified as a decimal with the fractional portion up to 8 decimal places i.e. 100.012. | ### Options @@ -99,10 +101,10 @@ You can specify the following options for the `dfx ledger approve` command. | Option | Description | |-------------------------------------|----------------------------------------------------------------------------------------| -| `--created-at-time ` | Specify the timestamp-nanoseconds for the `created_at_time` field on the transfer request. Useful for controlling [transaction-de-duplication](https://internetcomputer.org/docs/current/developer-docs/integrations/icrc-1/#transaction-deduplication-). | +| `--created-at-time ` | Specify the timestamp-nanoseconds for the `created_at_time` field on the transfer request. Useful for controlling transaction-de-duplication. | | `--expected-allowance `| The number of previously approved ICP. See [ICRC-2 standard](https://github.com/dfinity/ICRC-1/blob/main/standards/ICRC-2/README.md) for details. | | `--expires-at ` | Timestamp in nanoseconds until which the approval is valid. None means that the approval is valid indefinitely. | -| `--fee ` | Transaction fee, default is 0.00010000 ICP (10000 e8s) | +| `--fee ` | Transaction fee, default is 0.00010000 ICP (10000 e8s). | | `--from-subaccount ` | Approve ICP to be spent from this subaccount. | | `--memo ` | Specifies a numeric memo for this transaction. | | `--spender-subaccount ` | Allow this subaccount to spend ICP. | @@ -167,7 +169,7 @@ You can specify the following argument for the `dfx ledger balance` command. | Argument | Description | |----------|------------------------------------------------------------------------------------------------| -| `` | Specify an Account Identifier to get the balance of. If both this argument and `--of-principal` option are not specified, the currently-selected user identity will be used. | +| `` | Specify an account identifier to get the balance of. If both this argument and `--of-principal` option are not specified, the currently-selected user identity will be used. | ### Options @@ -180,7 +182,7 @@ You can specify the following argument for the `dfx ledger balance` command. ### Examples -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: +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 utility tokens associated with a known account identifier: ``` bash dfx ledger balance 03e3d86f29a069c6f2c5c48e01bc084e4ea18ad02b0eec8fccadf4487183c223 --network ic @@ -202,7 +204,7 @@ dfx ledger balance --of-principal tdrdy-ztedg-ftfrj-mwmqh-wjl3j-pty4c-j63lp-xfvt ## dfx ledger create-canister -Use the `dfx ledger create-canister` command to convert ICP tokens to cycles and to register a new canister identifier on the IC. +Use the `dfx ledger create-canister` command to convert ICP tokens to cycles and to register a new canister identifier on the mainnet. ### Basic usage @@ -225,14 +227,14 @@ You can specify the following argument for the `dfx ledger create-canister` comm | Option | Description | |-----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `--amount ` | Specify the number of ICP tokens to mint into cycles and deposit into destination canister. You can specify an amount as a number with up to eight (8) decimal places. | -| `--e8s ` | Specify ICP token fractional units—called e8s—as a whole number, where one e8 is smallest partition of an ICP token. For example, 1.05000000 is 1 ICP and 5000000 e8s. You can use this option on its own or in conjunction with the `--icp` option. | +| `--e8s ` | Specify ICP token fractional units (called e8s) as a whole number, where one e8 is smallest partition of an ICP token. For example, 1.05000000 is 1 ICP and 5000000 e8s. You can use this option on its own or in conjunction with the `--icp` option. | | `--fee ` | Specify a transaction fee. The default is 10000 e8s. | | `--icp ` | Specify ICP tokens as a whole number. You can use this option on its own or in conjunction with `--e8s`. | | `--max-fee ` | Specify a maximum transaction fee. The default is 10000 e8s. | | `--subnet-type ` | Specify the optional subnet type to create the canister on. If no subnet type is provided, the canister will be created on a random default application subnet. `dfx ledger show-subnet-types` can be used to list available subnet types. | | `--subnet ` | Specify the optional subnet to create the canister on. If no subnet is provided, the canister will be created on a random default application subnet. | | `--next-to ` | Create canisters on the same subnet as this canister. | -| `--created-at-time `| Specify the timestamp-nanoseconds for the `created_at_time` field on the ledger transfer request. Useful for controlling transaction-de-duplication. https://internetcomputer.org/docs/current/developer-docs/integrations/icrc-1/#transaction-deduplication- | +| `--created-at-time `| Specify the timestamp-nanoseconds for the `created_at_time` field on the ledger transfer request. Useful for controlling transaction-de-duplication. | ### Examples @@ -248,8 +250,10 @@ In this example, the command converts 1.25 ICP tokens into cycles and specifies If the transaction is successful, the ledger records the event and you should see output similar to the following: - Transfer sent at BlockHeight: 20 - Canister created with id: "53zcu-tiaaa-aaaaa-qaaba-cai" +``` +Transfer sent at BlockHeight: 20 +Canister created with id: "53zcu-tiaaa-aaaaa-qaaba-cai" +``` You can create a new canister by specifying separate values for ICP tokens and e8s by running a command similar to the following: @@ -275,8 +279,8 @@ If no amount is specified, 10T cycles are used by default. |Option |Description| |-------|-----------| -|`--all` |Deposit cycles to all of the canisters configured in the dfx.json file. | -|`--amount ` |ICP to mint into cycles and deposit into destination canister Can be specified as a Decimal with the fractional portion up to 8 decimal places i.e. 100.012 | +|`--all` |Deposit cycles to all of the canisters configured in the `dfx.json` file. | +|`--amount ` |ICP to mint into cycles and deposit into destination canister Can be specified as a decimal with the fractional portion up to 8 decimal places i.e. 100.012 | |`--canister ` |Specifies the name or id of the canister to receive the cycles deposit. You must specify either a canister name/id or the --all option. | |`--cycles ` | Specifies the amount of cycles to fabricate. | |`--e8s ` | Specify e8s as a whole number, helpful for use in conjunction with `--icp`| @@ -285,7 +289,7 @@ If no amount is specified, 10T cycles are used by default. ### Examples -If you are developing locally and want to add 8T cycles to all your canisters in your procject, you can do so like this: +If you are developing locally and want to add 8T cycles to all your canisters in your project, you can do so like this: ``` dfx ledger fabricate-cycles --all --cycles 8000000000000 @@ -311,15 +315,14 @@ Fabricating 8000000000000 cycles onto hello Fabricated 8000000000000 cycles, updated balance: 11_899_662_119_932 cycles ``` - ## dfx ledger notify -Use the `dfx ledger notify` command to notify the ledger about a transaction sent to the cycles minting canister. This command should only be used if `dfx ledger create-canister`, `dfx ledger top-up`, or `dfx cycles convert` successfully sent a message to the ledger, and a transaction was recorded at some block height, but for some reason the subsequent notify failed. +Use the `dfx ledger notify` command to notify the ledger about a transaction sent to the cycles minting canister. This command should only be used if `dfx ledger create-canister`, `dfx ledger top-up`, or `dfx cycles convert` successfully sent a message to the ledger, and a transaction was recorded at some block height but for some reason the subsequent notify failed. ### Basic usage ``` bash -dfx ledger notify [options] _block-height_ _destination-principal_ +dfx ledger notify [options] ``` ### Arguments @@ -329,11 +332,11 @@ You can specify the following argument for the `dfx ledger notify` command. | Argument | Description | |---------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `` | Specifies the block height at which the send transaction was recorded. | -| `` | Specifies the principal of the destination, either a canister identifier or the textual representation of a user principal. If the send transaction was for the `create-canister` command, specify the `controller` principal. If the send transaction was for the `top-up` command, specify the `canister ID`. | +| `` | Specifies the principal of the destination, either a canister identifier or the textual representation of a user principal. If the send transaction was for the `create-canister` command, specify the `controller` principal. If the send transaction was for the `top-up` command, specify the canister ID. | ### Examples -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`. +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 notify 75948 tsqwz-udeik-5migd-ehrev-pvoqv-szx2g-akh5s-fkyqc-zy6q7-snav6-uqe --network ic @@ -355,11 +358,11 @@ You can specify the following options for the `dfx ledger show-subnet-types` com | Option | Description | |-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| `--cycles-minting-canister-id ` | Canister id of the cycles minting canister. Useful if you want to test locally with a different id for the cycles minting canister. | +| `--cycles-minting-canister-id ` | Canister ID of the cycles minting canister. Useful if you want to test locally with a different ID for the cycles minting canister. | ### Examples -You can use the `dfx ledger show-subnet-types` command to list the available subnet types that can be chosen to create a canister on. If a specific cycles minting canister id is not provided, then the mainnet cycles minting canister id will be used. +You can use the `dfx ledger show-subnet-types` command to list the available subnet types that can be chosen to create a canister on. If a specific cycles minting canister ID is not provided, then the mainnet cycles minting canister ID will be used. For example, you can run the following command to get the subnet types available on mainnet: @@ -369,11 +372,13 @@ dfx ledger show-subnet-types This command displays output similar to the following: - ["Type1", "Type2", ..., "TypeN"] +``` +["Type1", "Type2", ..., "TypeN"] +``` ## dfx ledger top-up -Use the `dfx ledger top-up` command to top up a canister with cycles minted from ICP tokens. +Use the `dfx ledger top-up` command to top-up a canister with cycles minted from ICP tokens. ### Basic usage @@ -387,7 +392,7 @@ You can specify the following argument for the `dfx ledger top-up` command. | Argument | Description | |------------|--------------------------------------------------------------------------| -| `canister` | Specifies the canister identifier or name that you would like to top up. | +| `canister` | Specifies the canister identifier or name that you would like to top-up. | ### Options @@ -396,15 +401,15 @@ You can specify the following options for the `dfx ledger top-up` command. | Option | Description | |-----------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `--amount ` | Specifies the number of ICP tokens to mint into cycles and deposit into the destination canister. You can specify the amount as a number with up to eight (8) decimal places. | -| `--e8s ` | Specifies fractional units of an ICP token—called e8s—as a whole number, where one e8 is the smallest unit of an ICP token. For example, 1.05000000 is 1 ICP and 5000000 e8s. You can use this option on its own or in conjunction with the `--icp` option. | +| `--e8s ` | Specifies fractional units of an ICP token (called e8s) as a whole number, where one e8 is the smallest unit of an ICP token. For example, 1.05000000 is 1 ICP and 5000000 e8s. You can use this option on its own or in conjunction with the `--icp` option. | | `--fee ` | Specifies the transaction fee for the operation. The default is 10000 e8s. | | `--icp ` | Specifies ICP tokens as a whole number. You can use this option on its own or in conjunction with `--e8s`. | | `--max-fee ` | Specifies a maximum transaction fee. The default is 10000 e8s. | -| `--created-at-time `| Specify the timestamp-nanoseconds for the `created_at_time` field on the ledger transfer request. Useful for controlling transaction-de-duplication. https://internetcomputer.org/docs/current/developer-docs/integrations/icrc-1/#transaction-deduplication- | +| `--created-at-time `| Specify the timestamp-nanoseconds for the `created_at_time` field on the ledger transfer request. Useful for controlling transaction de-duplication. | ### Examples -You can use the `dfx ledger top-up` command to top up the cycles of a specific canister from the balance of ICP tokens you control. The canister identifier must be associated with a cycles wallet canister that is able to receive cycles. Alternatively, you can modify a non-cycles wallet canister to implement a method to receive cycles using system APIs described in the [Internet Computer Interface Specification](/docs/current/references/ic-interface-spec). +You can use the `dfx ledger top-up` command to top-up the cycles of a specific canister from the balance of ICP tokens you control. The canister identifier must be associated with a cycles wallet canister that is able to receive cycles. Alternatively, you can modify a non-cycles wallet canister to implement a method to receive cycles using system APIs described in the [IC interface specification](https://internetcomputer.org/docs/references/ic-interface-spec). 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: @@ -433,7 +438,7 @@ You can specify the following argument for the `dfx ledger transfer` command. | Argument | Description | |---------------------|-------------------------------------------------------------------------------------| -| `` | Specify the Account Identifier or address to which you want to transfer ICP tokens. | +| `` | Specify the account identifier or address to which you want to transfer ICP tokens. | | `--memo ` | Specifies a numeric memo for this transaction. | ### Options @@ -443,7 +448,7 @@ You can specify the following argument for the `dfx ledger transfer` command. | Option | Description | |---------------------|-------------------------------------------------------------------------------------| | `--amount ` | Specifies the number of ICP tokens to transfer. Can be specified as a number with up to eight (8) decimal places. | -| `--created-at-time `| Specify the timestamp-nanoseconds for the `created_at_time` field on the ledger transfer request. Useful for controlling transaction-de-duplication. https://internetcomputer.org/docs/current/developer-docs/integrations/icrc-1/#transaction-deduplication- | +| `--created-at-time `| Specify the timestamp-nanoseconds for the `created_at_time` field on the ledger transfer request. Useful for controlling transaction de-duplication. | | `--e8s ` | Specifies e8s as a whole number, where one e8 is smallest partition of an ICP token. For example, 1.05000000 is 1 ICP and 5000000 e8s. You can use this option alone or in conjunction with the `--icp` option. | | `--fee ` | Specifies a transaction fee. The default is 0.00010000 ICP (10000 e8s). | | `--from-subaccount ` | Specifies the subaccount from which you want to transfer ICP tokens. | @@ -453,7 +458,7 @@ You can specify the following argument for the `dfx ledger transfer` command. ### Examples -You can use the `dfx ledger transfer` command to send ICP to the Account Identifier of the destination. +You can use the `dfx ledger transfer` command to send ICP to the account identifier of the destination. For example, you can run the following command to check the account identifier associated with the principal you are currently using: @@ -463,7 +468,9 @@ dfx ledger account-id This command displays output similar to the following: - 30e596fd6c5ff5ad7b7d70bbbda1187c833e646c6251464da7f82bc217bba397 +``` +30e596fd6c5ff5ad7b7d70bbbda1187c833e646c6251464da7f82bc217bba397 +``` You can check the balance of this account by running the following command: @@ -473,7 +480,9 @@ dfx ledger balance --network ic This command displays output similar to the following: - 64.89580000 ICP +``` +64.89580000 ICP +``` Use the `dfx ledger transfer` command to send some of your ICP balance to another known destination using the following command: @@ -499,7 +508,7 @@ dfx ledger transfer --to-principal tdrdy-ztedg-ftfrj-mwmqh-wjl3j-pty4c-j63lp-xfv ## dfx ledger transfer-from -Use the `dfx ledger transfer-from` command to transfer ICP from the approver princiapl to another principal. Please check the [ICRC-2 standard](https://github.com/dfinity/ICRC-1/tree/main/standards/ICRC-2) for more information about token `approve` and `transfer-from`. +Use the `dfx ledger transfer-from` command to transfer ICP from the approver principal to another principal. Please check the [ICRC-2 standard](https://github.com/dfinity/ICRC-1/tree/main/standards/ICRC-2) for more information about token `approve` and `transfer-from`. ### Basic usage @@ -513,7 +522,7 @@ You must specify the following arguments for the `dfx ledger transfer-from` comm | Argument | Description | |---------------------|--------------------------------------------| -| `--amount ` | The number of ICPs to transfer. Can be specified as a Decimal with the fractional portion up to 8 decimal places i.e. 100.012. | +| `--amount ` | The number of ICPs to transfer. Can be specified as a decimal with the fractional portion up to 8 decimal places i.e. 100.012. | | `--from ` | Transfer ICP from this approver principal. | | `` | Transfer ICP to this principal. | @@ -523,7 +532,7 @@ You can specify the following options for the `dfx ledger transfer-from` command | Option | Description | |-------------------------------------|----------------------------------------------------------------------------------------| -| `--created-at-time ` | Specify the timestamp-nanoseconds for the `created_at_time` field on the transfer request. Useful for controlling [transaction-de-duplication](https://internetcomputer.org/docs/current/developer-docs/integrations/icrc-1/#transaction-deduplication-). | +| `--created-at-time ` | Specify the timestamp-nanoseconds for the `created_at_time` field on the transfer request. Useful for controlling transaction de-duplication. | | `--fee ` | Transaction fee, default is 0.00010000 ICP (10000 e8s). | | `--from-subaccount ` | Transfer ICP from this subaccount. | | `--memo ` | Specifies a numeric memo for this transaction. | diff --git a/docs/cli-reference/dfx-new.mdx b/docs/cli-reference/dfx-new.mdx index 50b7778240..611465d07c 100644 --- a/docs/cli-reference/dfx-new.mdx +++ b/docs/cli-reference/dfx-new.mdx @@ -4,7 +4,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -Use the `dfx new` command to create a new project for the IC. This command creates a default project structure with template files that you can modify to suit your dapp. You must specify the name of the project to you want to create. +Use the `dfx new` command to create a new project. This command creates a default project structure with template files that you can modify to suit your dapp. You must specify the name of the project to you want to create. You can use the `--dry-run` option to preview the directories and files to be created without adding them to the file system. @@ -24,8 +24,8 @@ You can use the following optional flags with the `dfx new` command: |-------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `--dry-run` | Generates a preview of the directories and files to be created for a new project without adding them to the file system. | | `--extras ` | Comma-separated list of additional features to add to the project template. `bitcoin` and `internet-identity` will insert the appropriate boilerplate into `dfx.json`, and `frontend-tests` adds a `vitest` skeleton to the frontend project. | -| `--frontend ` | Installs the template frontend code for the default project canister. The default value for the flag is `vanilla` if `node.js` is currently installed on your local computer. If `node.js` is not currently installed, you can set this flag to attempt to install `node.js` and the template file when creating the project or you can set the flag to `none` to skip the installation of template frontend code entirely. Possible values: `svelte`, `react`, `vue`, `vanilla`, `plain-assets`, `none`. | -| `--no-frontend` | Skips installing the frontend template code. This is the default behavior if `node.js` is currently not installed on your computer. Equivalent to `--frontend none`. | +| `--frontend ` | Installs the template frontend code for the default project canister. The default value for the flag is `vanilla` if NodeJS is currently installed on your local computer. If NodeJS is not currently installed, you can set this flag to attempt to install NodeJS and the template file when creating the project or you can set the flag to `none` to skip the installation of template frontend code entirely. Possible values: `svelte`, `react`, `vue`, `vanilla`, `plain-assets`, `none`. | +| `--no-frontend` | Skips installing the frontend template code. This is the default behavior if NodeJS is currently not installed on your computer. Equivalent to `--frontend none`. | | `--type ` | Selects the template backend code for the default project canister. The default value for the flag is `motoko`. Possible values: `motoko`, `rust`, `azle`, `kybra`. | ## Arguments @@ -35,7 +35,7 @@ You can specify the following argument for the `dfx new` command. | Argument | Description | |----------------|-------------------------------------------------------------------------| | `project_name` | Specifies the name of the project to create. This argument is required. | -| `--type` | Choose the canister type in the starter project, motoko and rust are available. The default is motoko. | +| `--type` | Choose the canister type in the starter project, `motoko`, `rust`, `azle`, and `kybra` are available. The default is `motoko`. | ## Examples diff --git a/docs/cli-reference/dfx-nns.mdx b/docs/cli-reference/dfx-nns.mdx index b4324f1c13..774963b17e 100644 --- a/docs/cli-reference/dfx-nns.mdx +++ b/docs/cli-reference/dfx-nns.mdx @@ -20,25 +20,24 @@ Depending on the `dfx nns` subcommand you specify, additional arguments, options | Command | Description | |-------------------------------------|-------------------------------------------------------------------------------| -| [`import`](#_dfx_nns_import) | Adds the NNS canisters to the local dfx.json as remote canisters. | -| [`install`](#_dfx_nns_install) | Deploys NNS canisters to the local dfx server. | +| [`import`](#_dfx_nns_import) | Adds the NNS canisters to the local `dfx.json` as remote canisters. | +| [`install`](#_dfx_nns_install) | Deploys NNS canisters to the local development environment. | | `help` | Displays usage information message for a specified subcommand. | To view usage information for a specific subcommand, specify the subcommand and the `--help` flag. For example, to see usage information for `dfx nns install`, you can run the following command: ``` bash -$ dfx nns install --help +dfx nns install --help ``` - ## dfx nns import -Use the `dfx nns import` command to add the NNS canisters to the local `dfx.json`. It also downloads the did files and sets the canister IDs of the NNS cansiters so that you can make API calls to NNS canisters. +Use the `dfx nns import` command to add the NNS canisters to the local `dfx.json`. It also downloads the `.did` files and sets the canister IDs of the NNS canisters so that you can make API calls to NNS canisters. ### Basic usage ``` bash -$ dfx nns import +dfx nns import ``` ### Flags @@ -51,25 +50,26 @@ You can use the following optional flags with the `dfx nns import` command. ### Examples -You can use the `dfx nns import` command to get did files and so query NNS canisters. +You can use the `dfx nns import` command to get `.did` files and query NNS canisters. ``` bash $ dfx nns import $ dfx canister call --network ic nns-governance get_pending_proposals '()' ``` -You can rename a network on import. For example, if you have `test-ic` set up as an alias of the `ic` network then you can set NNS canister IDs for `test-ic` with: +You can rename a network on import. For example, if you have `test-ic` set up as an alias of the `ic` network then you can set NNS canister IDs for `test-ic` with: ``` bash -$ dfx nns import --network-mapping test-ic=ic +dfx nns import --network-mapping test-ic=ic ``` ## dfx nns install -Use the `dfx nns install` command to install a local NNS. This provides local ledger and governance canisters as well as the GUI canisters Internet Identity and NNS-Dapp. +Use the `dfx nns install` command to install a local NNS. This creates local ledger and governance canisters as well as the GUI canisters Internet Identity and NNS dapp. ### Basic usage The local network needs to be set up with a very specific configuration: + ``` $ cat ~/.config/dfx/networks.json { @@ -89,11 +89,11 @@ This is because: * Some canisters are compiled to run on only very specific canister IDs and hostname/port pairs. -In addition, the local dfx server needs to be clean: +In addition, the local `dfx` server needs to be clean: ``` bash -$ dfx start --clean --background -$ dfx nns install +dfx start --clean --background +dfx nns install ``` This is because NNS canisters need to be installed before any others. @@ -104,23 +104,26 @@ This is because NNS canisters need to be installed before any others. #### Example: Making API calls to the local NNS. ``` bash -$ dfx stop -$ dfx start --clean --background -$ dfx nns install -$ dfx nns import -$ dfx canister call --network ic nns-governance get_pending_proposals '()' +dfx stop +dfx start --clean --background +dfx nns install +dfx nns import +dfx canister call --network ic nns-governance get_pending_proposals '()' ``` You can view the API calls that can be made for each NNS canister by looking at the interface definition files installed by `dfx nns import` in `candid/*.did`. The API methods are in the `service` section, which is usually located at the end of a `.did` file. It is easiest to start experimenting with methods that take no arguments. #### Example: Accessing ICP on the command line -Two accounts in the local ledger is initialized with ICP that can be used for testing. One uses a secp256k1 key, which is convenient for command line usage, another uses an ed25519 key, which is more convenient in web applications. +Two accounts in the local ledger is initialized with ICP that can be used for testing. One uses a secp256k1 key, which is convenient for command line usage, another uses an ed25519 key, which is more convenient in web applications. To use ICP on the command line: -* Start dfx and install the NNS, as described in [`install`](#_dfx_nns_install). -* Put this secret key into a file called `ident-1.pem`: + +1. Start `dfx` and install the NNS, as described in [`install`](#_dfx_nns_install). + +2. Put this secret key into a file called `ident-1.pem`: + ``` bash $ cat <ident-1.pem -----BEGIN EC PRIVATE KEY----- @@ -130,22 +133,31 @@ oUQDQgAEPas6Iag4TUx+Uop+3NhE6s3FlayFtbwdhRVjvOar0kPTfE/N8N6btRnd -----END EC PRIVATE KEY----- EOF ``` -* Check the key: (optional) + +3. Check the key: (optional) + ``` $ openssl ec -in ident-1.pem -noout -text ``` -* Create an identity with that secret key: + +4. Create an identity with that secret key: + ``` bash $ dfx identity import ident-1 ident-1.pem ``` -* Now you can use the (toy) funds: + +5. Now you can use the (test) funds: + ``` bash $ dfx ledger balance ``` To use ICP in an existing web application: -* Install the [@dfinity/agent npm module](https://www.npmjs.com/package/@dfinity/agent). -* Create an identity with this key pair: + +1. Install the [@dfinity/agent npm module](https://www.npmjs.com/package/@dfinity/agent). + +2. Create an identity with this key pair: + ``` const publicKey = "Uu8wv55BKmk9ZErr6OIt5XR1kpEGXcOSOC1OYzrAwuk="; const privateKey = @@ -164,4 +176,5 @@ To use ICP in an existing web application: return Uint8Array.from(window.atob(base64String), (c) => c.charCodeAt(0)); }; ``` -* That identity can now make API calls, including sending ICP. + +The identity can now make API calls, including sending ICP. diff --git a/docs/cli-reference/dfx-parent.mdx b/docs/cli-reference/dfx-parent.mdx index 5a466cf3e6..f92bb9346d 100644 --- a/docs/cli-reference/dfx-parent.mdx +++ b/docs/cli-reference/dfx-parent.mdx @@ -5,7 +5,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; The DFINITY command-line execution environment (`dfx`) is the primary tool for creating, deploying, and managing the -dapps you develop for the IC. +dapps you develop for ICP. Use the `dfx` parent command with flags and subcommands to specify the operations you want to perform with or without optional arguments. @@ -35,7 +35,7 @@ You can use the following options with the `dfx` command. |-------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `--identity ` | Specifies the user identity to use when running a command. | | `--logfile ` | Writes log file messages to the specified log file name if you use the `--log file` logging option. | -| `--log ` | Specifies the logging mode to use. + You can set the log mode to one of the following:
- `stderr` to log messages to the standard error facility.
- `tee` to write messages to both standard output and to a specified file name.
- `file` to write messages to a specified file name.
The default logging mode is stderr. | +| `--log ` | Specifies the logging mode to use. You can set the log mode to one of the following:
- `stderr` to log messages to the standard error facility.
- `tee` to write messages to both standard output and to a specified file name.
- `file` to write messages to a specified file name.
The default logging mode is stderr. | ## Subcommands @@ -49,25 +49,25 @@ For reference information and examples, select an appropriate subcommand. | bootstrap | Removed. Use the `start` command instead. | | [`build`](./dfx-build.mdx) | Builds canister output from the source code in your project. | | [`cache`](./dfx-cache.mdx) | Manages the `dfx` cache on the local computer. | -| [`canister`](./dfx-canister.mdx) | Manages deployed canisters . | +| [`canister`](./dfx-canister.mdx) | Manages deployed canisters. | | [`deploy`](./dfx-deploy.mdx) | Deploys all or a specific canister from the code in your project. By default, all canisters are deployed. | -| diagnose | Detects known problems in the current environment caused by upgrading DFX, and suggests commands to fix them. These commands can be batch-run automatically via `dfx fix` | -| fix | Applies one-time fixes for known problems in the current environment caused by upgrading DFX. Makes no changes that would not have been suggested by `dfx diagnose` | +| diagnose | Detects known problems in the current environment caused by upgrading `dfx`, and suggests commands to fix them. These commands can be batch-run automatically via `dfx fix` | +| fix | Applies one-time fixes for known problems in the current environment caused by upgrading `dfx`. Makes no changes that would not have been suggested by `dfx diagnose` | | generate | Generate type declarations for canisters from the code in your project | | [`help`](./dfx-help.mdx) | Displays usage information for a specified subcommand. | | [`identity`](./dfx-identity.mdx) | Enables you to create and manage the identities used to communicate with the IC. | | info | Displays information like port numbers and version numbers. | -| [`killall`](./dfx-killall.mdx) | Kills any dfx-related processes that have gotten stuck | -| [`ledger`](./dfx-ledger.mdx) | Enables you to interact with accounts in the ledger canister running on the Internet Computer. | +| [`killall`](./dfx-killall.mdx) | Kills any `dfx`-related processes that have gotten stuck. | +| [`ledger`](./dfx-ledger.mdx) | Enables you to interact with accounts in the ledger canister running on ICP. | | [`new`](./dfx-new.mdx) | Creates a new project. | -| [`ping`](./dfx-ping.mdx) | Sends a response request to the IC or the local development environment to determine network connectivity. If the connection is successful, a status reply is returned. | +| [`ping`](./dfx-ping.mdx) | Sends a response request to the mainnet or the local development environment to determine network connectivity. If the connection is successful, a status reply is returned. | | quickstart | Perform initial one time setup for your identity and/or wallet. | | remote | Commands used to work with remote canisters. | -| [`replica`](./dfx-replica.mdx) | Removed. Use the `start` command instead. | +| [`replica`](./dfx-replica.mdx) | Removed. Use the `start` command instead. | | [`schema`](./dfx-schema.mdx) | Prints the schema for `dfx.json`. | -| [`start`](./dfx-start.mdx) | Starts the local development environment a web server for the current project. | +| [`start`](./dfx-start.mdx) | Starts the local development environment. | | [`stop`](./dfx-stop.mdx) | Stops the local development environment. | -| [`upgrade`](./dfx-upgrade.mdx) | Upgrades the version of `dfx` installed on the local computer to the latest version available. | +| [`upgrade`](./dfx-upgrade.mdx) | Replaced by `dfxvm`. The command `dfx upgrade` doesn't work with `dfxvm`. To upgrade `dfx`, run: `dfxvm update`. | | [`wallet`](./dfx-wallet.mdx) | Enables you to manage cycles, controllers, custodians, and addresses for the default cycles wallet associated with the currently-selected identity. | ## Examples @@ -121,4 +121,6 @@ for specific operations. 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 canister call accounts modify_profile '("Kris Smith")' --identity devops +``` +dfx canister call accounts modify_profile '("Kris Smith")' --identity devops +``` \ No newline at end of file diff --git a/docs/cli-reference/dfx-ping.mdx b/docs/cli-reference/dfx-ping.mdx index 73e5433556..b1a05c85e4 100644 --- a/docs/cli-reference/dfx-ping.mdx +++ b/docs/cli-reference/dfx-ping.mdx @@ -4,7 +4,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -Use the `dfx ping` command to check connectivity to the IC or a testnet. This command enables you to verify that you can connect to the environment where you want to deploy to. +Use the `dfx ping` command to check connectivity to a network. This command enables you to verify that you can connect to the environment where you want to deploy to. To ping your local server, please note that you can only run this command from within the project directory structure. For example, if your project name is `hello_world`, your current working directory must be the `hello_world` top-level project directory or one of its subdirectories. @@ -22,11 +22,11 @@ You can specify the following argument for the `dfx ping` command. | Argument | Description | |----------|---------------------------------------------------------------| -| provider | Specifies the IC or testnet URL that you want to use. | +| provider | Specifies the network URL that you want to use. | ## Examples -You can use the `dfx ping` command to check whether the IC is currently available at a specific network address by running a command similar to the following: +You can use the `dfx ping` command to check whether the mainnet is currently available at a specific network address by running a command similar to the following: ``` bash dfx ping https://icp-api.io @@ -36,6 +36,7 @@ If the IC is running on the specified network provider address, the command retu ```json { - "ic_api_version": "0.8" + "replica_health_status": "healthy", + "root_key": [48, 129, 130, 48, 29, 6, 13, 43, 6, 1, 4, 1, 130, 220, 124, 5, 3, 1, 2, 1, 6, 12, 43, 6, 1, 4, 1, 130, 220, 124, 5, 3, 2, 1, 3, 97, 0, 129, 76, 14, 110, 199, 31, 171, 88, 59, 8, 189, 129, 55, 60, 37, 92, 60, 55, 27, 46, 132, 134, 60, 152, 164, 241, 224, 139, 116, 35, 93, 20, 251, 93, 156, 12, 213, 70, 217, 104, 95, 145, 58, 12, 11, 44, 197, 52, 21, 131, 191, 75, 67, 146, 228, 103, 219, 150, 214, 91, 155, 180, 203, 113, 113, 18, 248, 71, 46, 13, 90, 77, 20, 80, 95, 253, 116, 132, 176, 18, 145, 9, 28, 95, 135, 185, 136, 131, 70, 63, 152, 9, 26, 11, 170, 174] } ``` \ No newline at end of file diff --git a/docs/cli-reference/dfx-quickstart.mdx b/docs/cli-reference/dfx-quickstart.mdx index 9528af5efa..62801c131f 100644 --- a/docs/cli-reference/dfx-quickstart.mdx +++ b/docs/cli-reference/dfx-quickstart.mdx @@ -4,10 +4,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -Use the `dfx quickstart` command to perform initial one time setup for your identity and/or wallet. This command -can be run anytime to repeat the setup process or to be used as an informational command, printing -information about -your ICP balance, current ICP to XDR conversion rate, and more. +Use the `dfx quickstart` command to perform initial one time setup for your identity and/or wallet. This command can be run anytime to repeat the setup process or to be used as an informational command, printing information about your ICP balance, current ICP to XDR conversion rate, and more. ## Basic usage @@ -21,7 +18,7 @@ You can use the following optional flags with the `dfx quickstart` command. | Flag | Description | |-------------------|----------------------------------------------------------------------------------------------------------------------------------------| -| `--identity` | The user identity to run this command as. It contains your principal as well as some things DFX associates with it such as the wallet. | +| `--identity` | The user identity to run this command as. It contains your principal as well as some things `dfx` associates with it such as the wallet. | ## Options @@ -39,12 +36,12 @@ To run a guided setup, run `dfx quickstart` ``` bash dfx quickstart ``` + ```shell -Your DFX user principal: xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxxxx-xxx -Your ledger account address: xxxxx -Your ICP balance: 1234.567 ICP -Conversion rate: 1 ICP <> 3.7950 XDR -Import an existing wallet? no -Spend 2.63504611 ICP to create a new wallet with 10 TC? no -Run this command again at any time to continue from here. +Your DFX user principal: hoqq7-3eo6j-dee4s-aiabk-6rqxw-kwgyo-rhru7-bdgmk-k5ipv-chkhx-cqe +Your ledger account address: 594369ede58d796ee76912d66201409930c9528d804f49a8e3f432bff957eae9 +Your ICP balance: 3.99910000 ICP +Conversion rate: 1 ICP <> 3.3357 XDR +Mainnet wallet canister: mwylj-4aaaa-aaaak-aflyq-cai +Mainnet wallet balance: 66.28 TC ``` diff --git a/docs/cli-reference/dfx-replica.mdx b/docs/cli-reference/dfx-replica.mdx index 7320d40ac5..3f904a1b33 100644 --- a/docs/cli-reference/dfx-replica.mdx +++ b/docs/cli-reference/dfx-replica.mdx @@ -4,4 +4,4 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -**NOTE**: The replica command has been removed. Please use the [dfx start](./dfx-start.mdx) command instead. +The replica command has been removed. Please use the [dfx start](./dfx-start.mdx) command instead. diff --git a/docs/cli-reference/dfx-schema.mdx b/docs/cli-reference/dfx-schema.mdx index ee881dccb9..33fdcb9c2d 100644 --- a/docs/cli-reference/dfx-schema.mdx +++ b/docs/cli-reference/dfx-schema.mdx @@ -18,7 +18,7 @@ You can use the following option with the `dfx schema` command. | Option | Description | |------------------------|----------------------------------------------------------------------------| -| `--for ` | Display schema for which JSON file. (default: dfx) | +| `--for ` | Display schema for which JSON file. (default: `dfx`) | | `--outfile ` | Specifies a file to output the schema to instead of printing it to stdout. | The parameter passed to `--for` can be one of the following: @@ -28,8 +28,8 @@ The parameter passed to `--for` can be one of the following: | dfx | dfx.json | | networks | networks.json | | dfx-metadata | dfx-related metadata stored in canister and accessible with `dfx canister metadata dfx` | -| extension-manifest | extension.json [example][example-extension-json] | -| extension-dependencies | dependencies.json [example][example-dependencies-json] | +| extension-manifest | extension.json [View an example][example-extension-json] | +| extension-dependencies | dependencies.json [View an example][example-dependencies-json] | ## Examples @@ -51,7 +51,7 @@ You can print the schema for the "dfx" metadata JSON (which contains fields such dfx schema --for dfx-metadata ``` -If you want to write the schema for dfx.json to `path/to/file/schema.json`, you can do so by running the following command: +If you want to write the schema for `dfx.json` to `path/to/file/schema.json`, you can do so by running the following command: ``` bash dfx schema --outfile path/to/file/schema.json diff --git a/docs/cli-reference/dfx-sns.mdx b/docs/cli-reference/dfx-sns.mdx index b5e0ae59d5..cb1f40ebd1 100644 --- a/docs/cli-reference/dfx-sns.mdx +++ b/docs/cli-reference/dfx-sns.mdx @@ -5,10 +5,12 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; :::caution -The `dfx sns` command is no longer part of dfx, and has now been turned into the dfx extension. In order to obtain it, please run `dfx extension install sns`. +The `dfx sns` command is no longer part of dfx, and has now been turned into a `dfx` extension. In order to obtain it, please run `dfx extension install sns`. ::: -Use the `dfx sns` subcommands to simulate decentralizing a dapp. +Use the `dfx sns` subcommands to simulate handing a dapp off to the community for decentralized governance. + +## Basic usage The basic syntax for running `dfx sns` commands is: @@ -31,10 +33,9 @@ To view usage information for a specific subcommand, specify the subcommand and dfx sns validate --help ``` - ## dfx sns create -Use the `dfx sns create` command to create an SNS configuration file. The configuration file specifies important, legally and financially relevant details about dapp decentralization. The file leaves blank parameters such as token name; you will need to fill these in. +Use the `dfx sns create` command to create an SNS configuration file. The configuration file specifies important, legal and financial details about the dapp's decentralization. The file leaves blank parameters such as token name; you will need to fill these in. ### Basic usage @@ -63,11 +64,12 @@ dfx sns validate ### Examples -You can use the `dfx sns validate` command to verify that a configuration template is valid. It is not; it needs details such as token name: +You can use the `dfx sns validate` command to verify that a configuration template is valid. It is not, it needs details such as token name: ``` bash dfx sns config create ``` + Fill in the blank fields, then: ``` bash dfx sns config validate @@ -77,26 +79,31 @@ dfx sns config validate Use the `dfx sns deploy` command to create SNS canisters according to the local configuration file. -Note: Deploying SNS canisters does not require a proposal, however there is a hefty fee. Please don't create canisters on mainnet until you have tested your configuration locally and are sure that you are happy with it. +Note: Deploying SNS canisters on the mainnet does not require a proposal; however there is a hefty fee. Please don't create canisters on mainnet until you have tested your configuration locally and are sure that you are happy with it. ### Basic usage ``` bash -dfx sns deploy +dfx sns deploy --network=ic ``` ### Examples Create an SNS on the local testnet: + ``` bash dfx sns config create ``` + Fill in the blank fields, then: + ``` bash dfx sns config validate dfx sns deploy ``` -You can now verify that the sns canisters have been created. E.g.: + +You can now verify that the sns canisters have been created. + ``` dfx canister info sns_root dfx canister info sns_ledger diff --git a/docs/cli-reference/dfx-start.mdx b/docs/cli-reference/dfx-start.mdx index 5c9e3f6dfa..6001d44472 100644 --- a/docs/cli-reference/dfx-start.mdx +++ b/docs/cli-reference/dfx-start.mdx @@ -6,7 +6,7 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; Use the `dfx start` command to start a local development environment and web server processes. This command must be run before you can deploy canisters to the local development environment and test your dapps during development. -By default, all local dfx projects will use PocketIC to create this local development environment. You can run `dfx start` and `dfx stop` from any directory. See [local server configuration](#local-server-configuration) and [project-specific local networks](#project-specific-local-networks) below for exceptions. +By default, all local `dfx` projects will use PocketIC to create this local development environment. You can run `dfx start` and `dfx stop` from any directory. See [local server configuration](#local-server-configuration) and [project-specific local networks](#project-specific-local-networks) below for exceptions. ## Basic usage @@ -22,8 +22,8 @@ You can use the following optional flags with the `dfx start` command. |--------------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `--background` | Starts the local development environment and web server processes in the background and waits for a reply before returning to the shell. | | `--clean` | Starts the local development environment and web server processes in a clean state by removing checkpoints from your project cache. You can use this flag to set your project cache to a new state when troubleshooting or debugging. | -| `--enable-bitcoin` | Enables bitcoin integration. | -| `--enable-canister-http` | Enables canister HTTP requests. (deprecated: now enabled by default) | +| `--enable-bitcoin` | Enables Bitcoin integration. | +| `--enable-canister-http` | Deprecated and now enabled by default. | | `--pocketic` | Runs [PocketIC](https://github.com/dfinity/pocketic) instead of the replica. PocketIC is the default if no flag is used. | ## Options @@ -33,9 +33,9 @@ You can use the following option with the `dfx start` command. | Option | Description | |-----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | `--host host` | Specifies the host interface IP address and port number to bind the frontend to. The default for the local shared network is `127.0.0.1:4943`, while the default for a project-specific network is '127.0.0.1:8000'. | -| `--bitcoin-node host:port` | Specifies the address of a bitcoind node. Implies `--enable-bitcoin`. | +| `--bitcoin-node host:port` | Specifies the address of a `bitcoind` node. Implies `--enable-bitcoin`. | | `--artificial-delay milliseconds` | Specifies the delay that an update call should incur. Default: 600ms | -| `--domain domain` | A domain that can be served. Can be specified more than once. These are used for canister resolution [default: localhost] | +| `--domain domain` | A domain that can be served. Can be specified more than once. These are used for canister resolution [default: localhost] | ## Examples @@ -69,7 +69,7 @@ more .dfx/pid `dfx start` manages a PocketIC server that provides a local development environment. Running `dfx deploy` and other commands will manage canisters on this local network in the same way that `dfx deploy --network ic` deploys projects to the mainnet. -If run from outside a dfx project directory, or if `dfx.json` does not define the `local` network, then `dfx start` looks for the `local` network definition in `$HOME/.config/dfx/networks.json`. If this file does not exist or does not contain a definition for the `local` network, then dfx uses the following default definition: +If run from outside a `dfx` project directory, or if `dfx.json` does not define the `local` network, then `dfx start` looks for the `local` network definition in `$HOME/.config/dfx/networks.json`. If this file does not exist or does not contain a definition for the `local` network, then `dfx` uses the following default definition: ``` { @@ -80,7 +80,7 @@ If run from outside a dfx project directory, or if `dfx.json` does not define th } ``` -dfx stores data for the shared local network in one of the following locations, depending on your operating system: +`dfx` stores data for the shared local network in one of the following locations, depending on your operating system: - `$HOME/.local/share/dfx/network/local` (Linux) - `$HOME/Library/Application Support/org.dfinity.dfx/network/local` (macOS) diff --git a/docs/cli-reference/dfx-stop.mdx b/docs/cli-reference/dfx-stop.mdx index fc647a9f94..d801b3c0f9 100644 --- a/docs/cli-reference/dfx-stop.mdx +++ b/docs/cli-reference/dfx-stop.mdx @@ -4,9 +4,9 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -Use the `dfx stop` command to stop the local development environment processes that you currently have running on your computer. In most cases, you run the canister execution environment locally so that you can deploy canisters and test your dapps during development. To simulate the connection to the IC, these processes run continuously either in a terminal shell where you started them or the in the background until you stop or kill them. +Use the `dfx stop` command to stop the local development environment processes that you currently have running on your computer. In most cases, you run the canister execution environment locally so that you can deploy canisters and test your dapps during development. To simulate the connection to the mainnet, these processes run continuously either in a terminal shell where you started them or the in the background until you stop or kill them. -You can run this command from any directory unless you are working with a dfx.json project that defines a project-specific local network. See [Local Server Configuration](dfx-start.mdx#local-server-configuration) for details. +You can run this command from any directory unless you are working with a `dfx.json` project that defines a project-specific local network. See [local server configuration](dfx-start.mdx#local-server-configuration) for details. ## Basic usage @@ -27,16 +27,19 @@ If the local development environment is running in a current shell rather than i The current process identifier (`pid`) for the canister execution environment process started by `dfx` is recorded in a file named `pid`. You can view the process identifier before running the `dfx stop` command by running one of the following commands: For a project-specific local network: + ``` bash cat .dfx/network/local/pid ``` -For the shared local network, on Linux: +For the shared local network on Linux: + ``` bash cat $HOME/.local/share/dfx/network/local/pid ``` -For the shared local network, on MacOS: +For the shared local network on MacOS: + ``` bash cat '$HOME/Library/Application Support/org.dfinity.dfx/network/local/pid' ``` @@ -47,7 +50,7 @@ This command displays a process identifier similar to the following: 1896 ``` -If you are still having trouble with a persistent service running after attempting to stop, you can terminate all running jobs with: +If you are still having trouble with a persistent service running after attempting to stop, you can terminate all running processes with: ``` bash dfx killall diff --git a/docs/cli-reference/dfx-upgrade.mdx b/docs/cli-reference/dfx-upgrade.mdx index 329eb4a331..b450d91414 100644 --- a/docs/cli-reference/dfx-upgrade.mdx +++ b/docs/cli-reference/dfx-upgrade.mdx @@ -4,6 +4,6 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; -> **NOTE**: The upgrade command has been removed. Please use the [dfx version manager][dfxvm] instead. +The upgrade command has been removed. Please use the [dfx version manager][dfxvm] instead. [dfxvm]: https://github.com/dfinity/dfxvm diff --git a/docs/cli-reference/dfx-wallet.mdx b/docs/cli-reference/dfx-wallet.mdx index 19cd69bff2..dc96b23793 100644 --- a/docs/cli-reference/dfx-wallet.mdx +++ b/docs/cli-reference/dfx-wallet.mdx @@ -6,8 +6,9 @@ import { MarkdownChipRow } from "/src/components/Chip/MarkdownChipRow"; Use the `dfx wallet` command with subcommands and flags to manage the cycles wallets of your identities and to send cycles to the wallets of other account cycles wallet canisters. -The basic syntax for running the `dfx wallet` commands is: +## Basic usage +The basic syntax for running the `dfx wallet` commands is: ```bash dfx wallet [option] [flag] @@ -28,17 +29,17 @@ For reference information and examples that illustrate using `dfx wallet` comman ---------|----------------------------------- |[`add-controller`](#dfx-wallet-add-controller) | Add a controller using the selected identity's principal. | |[`addresses`](#dfx-wallet-addresses)|Displays the address book of the cycles wallet.| -|[`authorize`](#dfx-wallet-authorize)|Authorize a custodian by principal for the selected identity's cycles wallet| +|[`authorize`](#dfx-wallet-authorize)|Authorize a custodian by principal for the selected identity's cycles wallet.| |[`balance`](#dfx-wallet-balance)|Displays the cycles wallet balance of the selected identity. |[`controllers`](#dfx-wallet-controllers) |Displays a list of the selected identity's cycles wallet controllers. |[`custodians`](#dfx-wallet-custodians) |Displays a list of the selected identity's cycles wallet custodians. |[`deauthorize`](#dfx-wallet-deauthorize) | Deauthorize a cycles wallet custodian using the custodian's principal. -|`help`|Displays a usage message and the help of the given subcommand(s). +|`help`|Displays a usage message and the help info for the given subcommand(s). |[`name`](#dfx-wallet-name) |Returns the name of the cycles wallet if you've used the `dfx wallet set-name` command. |[`remove-controller`](#dfx-wallet-remove-controller) |Removes a specified controller from the selected identity's cycles wallet. |[`send`](#dfx-wallet-send) |Sends a specified amount of cycles from the selected identity's cycles wallet to another canister. |[`set-name`](#dfx-wallet-set-name) |Specify a name for your cycles wallet. -|[`upgrade`](#dfx-wallet-upgrade) |Upgrade the cycles wallet's Wasm module to the current Wasm bundled with DFX. +|[`upgrade`](#dfx-wallet-upgrade) |Upgrade the cycles wallet's Wasm module to the current Wasm bundled with `dfx`. ## Using your wallet @@ -47,7 +48,7 @@ After you have used the `dfx identity deploy-wallet` command to create a cycles ## dfx wallet add-controller -Use the `dfx wallet add-controller` to add a controller to the wallet. An identity assigned the role of Controller has the most privileges and can perform the following actions on the selected identity's cycles wallet: +Use the `dfx wallet add-controller` to add a controller to the wallet. An identity assigned the role of controller has the most privileges and can perform the following actions on the selected identity's cycles wallet: * Rename the cycles wallet. @@ -70,7 +71,6 @@ A controller is also a custodian and can perform the following actions associate ### Basic usage - ``` dfx wallet add-controller [option] [flag] ``` @@ -82,7 +82,7 @@ You can use the following options with the `dfx canister call` command. |Option |Description| --------|------------| -|`--network ` |Specifies the environment (e.g., Internet Computer or testnet) of the controller you want to add. +|`--network` |Override the environment to connect to. By default, the local development environment is used. A valid URL (starting with `http:` or `https:`) can be specified here, e.g. "http://localhost:12345/" is a valid network name. ### Arguments @@ -110,7 +110,7 @@ Added b5quc-npdph-l6qp4-kur4u-oxljq-7uddl-vfdo6-x2uo5-6y4a6-4pt6v-7qe as a contr ## dfx wallet addresses -Use the `dfx wallet addresses` command to display the wallet's address book.The address entries contain the principal and `role` (`Contact`, `Custodian`, or `Controller`), and might contain a `name`, and `kind` (`Unknown`, `User`, or `Canister`) associated with the address. +Use the `dfx wallet addresses` command to display the wallet's address book. The address entries contain the principal and `role` (`Contact`, `Custodian`, or `Controller`), and might contain a `name`, and `kind` (`Unknown`, `User`, or `Canister`) associated with the address. ### Basic usage @@ -148,7 +148,6 @@ Use the `dfx wallet authorize` command to authorize a custodian for the wallet. ### Basic usage - ``` dfx wallet authorize [flag] ``` @@ -163,7 +162,7 @@ Use the following necessary argument with the `dfx wallet authorize` command. ### Example -For example, to add alice_auth as a custodian, specify her principal in the following command: +For example, to add `alice_auth` as a custodian, specify the identity's principal in the following command: ``` dfx wallet authorize dheus-mqf6t-xafkj-d3tuo-gh4ng-7t2kn-7ikxy-vvwad-dfpgu-em25m-2ae @@ -181,7 +180,6 @@ Use the `dfx wallet balance` command to display the balance of the cycles wallet ### Basic usage - ``` dfx wallet balance ``` @@ -267,11 +265,10 @@ hpnmi-qgxsv-tgecj-hmjyn-gmfft-vbego-lpcax-ou4ld-oh7kr-l3nu2-yae Use the `dfx wallet deauthorize` command to remove a custodian from the cycles wallet. -NOTE: that this will also remove the role of controller if the custodian is also a controller. +NOTE: This will also remove the role of controller if the custodian is also a controller. ### Basic usage - ``` dfx wallet deauthorize [flag] ``` @@ -287,7 +284,7 @@ Use the following necessary argument with the `dfx wallet deauthorize` command. ### Example -For example, to remove "alice_auth" as a custodian, specify her principal in the following command: +For example, to remove `alice_auth` as a custodian, specify her principal in the following command: ``` @@ -313,10 +310,10 @@ dfx wallet name [flag] ### Example -If you have named your cycles wallet "Terrances_wallet", then the command would return the following: +If you have named your cycles wallet "my_wallet", then the command would return the following: ``` -Terrances_wallet +my_wallet ``` ## dfx wallet remove-controller @@ -334,20 +331,22 @@ dfx wallet remove-controller [flag] Use the following necessary argument with the `dfx wallet remove-controller` command. -|Argument |Description - -|`` | Specify the principal of the controller you want to remove. +|Argument |Description | +|---------|-----------| +|`` | Specify the principal of the controller you want to remove. | ### Example -For example, to remove alice_auth as a controller, specify her principal in the following command: +For example, to remove `alice_auth` as a controller, specify the identity's principal in the following command: ``` dfx wallet remove-controller dheus-mqf6t-xafkj-d3tuo-gh4ng-7t2kn-7ikxy-vvwad-dfpgu-em25m-2ae ``` + The command outputs something similar to the following: + ``` Removed dheus-mqf6t-xafkj-d3tuo-gh4ng-7t2kn-7ikxy-vvwad-dfpgu-em25m-2ae as a controller. ``` @@ -369,7 +368,7 @@ You can use the following option with the `dfx wallet send` command. |Option |Description -----------|---------- -|`--network` |Override the environment to connect to. By default, the local development environment is used. A valid URL (starting with `http:` or `https:`) can be specified here. E.g. "http://localhost:12345/" is a valid network name. +|`--network` |Override the environment to connect to. By default, the local development environment is used. A valid URL (starting with `http:` or `https:`) can be specified here, e.g. "http://localhost:12345/" is a valid network name. ### Arguments @@ -377,21 +376,21 @@ You must specify the following arguments for the `dfx wallet send` command. |Argument |Description -----------|---------- -|`` |Specify the destination canister using its Canister ID. +|`` |Specify the destination canister using its canister ID. |`` |Specify the number of cycles to send. ### Examples Send cycles from the selected identity's cycles wallet to another cycles wallet. -For example, to send 2,000,000,000 cycles from the cycles wallet of the selected identity, ``, to the cycles wallet of the destination identity, `` with a wallet address `r7inp-6aaaa-aaaaa-aaabq-cai`, run the following command: +For example, to send 2_000_000_000 cycles from the cycles wallet of the selected identity, ``, to the cycles wallet of the destination identity, `` with a wallet address `r7inp-6aaaa-aaaaa-aaabq-cai`, run the following command: ``` dfx wallet send r7inp-6aaaa-aaaaa-aaabq-cai 2000000000 ``` -If the transfer is successful, the command does not displays any output. +If the transfer is successful, the command does not display any output. ## dfx wallet set-name @@ -400,7 +399,7 @@ Use the `dfx wallet set-name` command to assign a name to the selected identity' ### Basic usage ``` - dfx wallet set-name [flag] +dfx wallet set-name [flag] ``` ### Arguments @@ -414,25 +413,25 @@ You must specify the following arguments for the `dfx wallet set-name` command. ### Example -If you want to set the name of the current identity's cycles wallet to "Terrances_wallet" you can run the following command: +If you want to set the name of the current identity's cycles wallet to "my_wallet" you can run the following command: ``` -dfx wallet set-name Terrances_wallet +dfx wallet set-name my_wallet ``` ## dfx wallet upgrade -Use the `dfx wallet upgrade` command to upgrade the cycle wallet's Wasm module to the current Wasm bundled with DFX. +Use the `dfx wallet upgrade` command to upgrade the cycle wallet's Wasm module to the current Wasm bundled with `dfx`. ### Basic usage - ``` - dfx wallet upgrade [flag] +dfx wallet upgrade [flag] ``` ### Example + To upgrade the Wasm module to the latest version, run the following command: ```