From b81a585c3c43b25de01950803ac4621aaeaa36b0 Mon Sep 17 00:00:00 2001 From: ais <97464093+aisconnolly@users.noreply.github.com> Date: Tue, 17 May 2022 15:41:33 +0200 Subject: [PATCH] adding cli-ref markdown files Hi SDK folks! I am adding the cli-ref files here, which will then be pulled into /portal and compiled into the references section in the docs. Just one small question about `bootstrap` and `generate`, they were not included in the old docs - should they be linked? (They are there now just in case.) --- docs/cli-reference/dfx-bootstrap.md | 58 +++ docs/cli-reference/dfx-build.md | 60 +++ docs/cli-reference/dfx-cache.md | 157 ++++++ docs/cli-reference/dfx-canister.md | 768 ++++++++++++++++++++++++++++ docs/cli-reference/dfx-config.md | 66 +++ docs/cli-reference/dfx-deploy.md | 74 +++ docs/cli-reference/dfx-envars.md | 41 ++ docs/cli-reference/dfx-generate.md | 69 +++ docs/cli-reference/dfx-help.md | 31 ++ docs/cli-reference/dfx-identity.md | 408 +++++++++++++++ docs/cli-reference/dfx-ledger.md | 391 ++++++++++++++ docs/cli-reference/dfx-new.md | 46 ++ docs/cli-reference/dfx-parent.md | 99 ++++ docs/cli-reference/dfx-ping.md | 42 ++ docs/cli-reference/dfx-replica.md | 36 ++ docs/cli-reference/dfx-start.md | 56 ++ docs/cli-reference/dfx-stop.md | 48 ++ docs/cli-reference/dfx-upgrade.md | 42 ++ docs/cli-reference/dfx-wallet.md | 515 +++++++++++++++++++ docs/cli-reference/index.md | 49 ++ 20 files changed, 3056 insertions(+) create mode 100644 docs/cli-reference/dfx-bootstrap.md create mode 100644 docs/cli-reference/dfx-build.md create mode 100644 docs/cli-reference/dfx-cache.md create mode 100644 docs/cli-reference/dfx-canister.md create mode 100644 docs/cli-reference/dfx-config.md create mode 100644 docs/cli-reference/dfx-deploy.md create mode 100644 docs/cli-reference/dfx-envars.md create mode 100644 docs/cli-reference/dfx-generate.md create mode 100644 docs/cli-reference/dfx-help.md create mode 100644 docs/cli-reference/dfx-identity.md create mode 100644 docs/cli-reference/dfx-ledger.md create mode 100644 docs/cli-reference/dfx-new.md create mode 100644 docs/cli-reference/dfx-parent.md create mode 100644 docs/cli-reference/dfx-ping.md create mode 100644 docs/cli-reference/dfx-replica.md create mode 100644 docs/cli-reference/dfx-start.md create mode 100644 docs/cli-reference/dfx-stop.md create mode 100644 docs/cli-reference/dfx-upgrade.md create mode 100644 docs/cli-reference/dfx-wallet.md create mode 100644 docs/cli-reference/index.md diff --git a/docs/cli-reference/dfx-bootstrap.md b/docs/cli-reference/dfx-bootstrap.md new file mode 100644 index 0000000000..d2e50c2db5 --- /dev/null +++ b/docs/cli-reference/dfx-bootstrap.md @@ -0,0 +1,58 @@ +# dfx bootstrap {#_dfx_bootstrap} + +Use the `dfx bootstrap` command to start the bootstrap web server defined in the `dfx.json` configuration file or specified using command-line options. + +The bootstrap web server you specify is used to serve the front-end static assets for your project. + +## Basic usage {#_basic_usage} + +``` bash +dfx bootstrap [option] +``` + +## Flags {#_flags} + +You can use the following optional flags with the `dfx bootstrap` command. + +| Flag | Description | +-----------------------|-----------------------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +## Options {#_options} + +You can specify the following options for the `dfx bootstrap` command. + +| Option | Description | +-----------------------|-----------------| +| `ip` | Specifies the IP address that the bootstrap server listens on. If you don't specify an IP address, the `address` setting you have configured in the `dfx.json` configuration file is used. By default, the server address is 127.0.0.1. | +| \--network | Specifies the network to connect to if you want to override the default local network endpoint (`http://127.0.0.1:8080/api`).| +| \--port | Specifies the port number that the bootstrap server listens on. By default, port number 8081 is used. | +| \--root | Specifies the directory containing static assets served by the bootstrap server. By default, the path to static assets is: `$HOME/.cache/dfinity/versions/$DFX_VERSION/js-user-library/dist/bootstrap`. | +| \--timeout | Specifies the maximum amount of time, in seconds, the bootstrap server will wait for upstream requests to complete. By default, the bootstrap server waits for a maximum of 30 seconds. | + +## Examples {#_examples} + +You can use the `dfx bootstrap` command to start a web server for your application using custom settings, including a specific server address, port number, and static asset location. + +For example, to start the bootstrap server using a specific IP address and port number, you would run a command similar to the following: + +``` bash +dfx bootstrap --ip 192.168.47.1 --port 5353 +``` + +The command displays output similar to the following: + +``` bash +binding to: V4(192.168.47.1:5353) +replica(s): \http://127.0.0.1:8080/api +Webserver started... +``` + +To use the default server address and port number but specify a custom location for static assets and longer timeout period, you might run a command similar to the following: + +``` bash +dfx bootstrap --root $HOME/ic-projects/assets --timeout 60 +``` + +You can use CTRL-C to stop the bootstrap server. diff --git a/docs/cli-reference/dfx-build.md b/docs/cli-reference/dfx-build.md new file mode 100644 index 0000000000..db60d3551f --- /dev/null +++ b/docs/cli-reference/dfx-build.md @@ -0,0 +1,60 @@ +# dfx build + +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. + +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. + +## Basic usage + +``` bash +dfx build [flag] [option] [--all | canister_name] +``` + +## Flags + +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. | +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +## Options + +You can specify the following option 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. | + +## Arguments + +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.) | + +## 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` canister and one `hello_world_assets` canister [like this](../_attachments/sample-dfx.json), 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` canister contains the main program code and the `hello_world_assets` canister store frontend code and assets. If you want to keep the `hello_world_assets` canister defined in the `dfx.json` file, but only build the backend program, you could run the following command: + +``` bash +dfx build hello_world +``` + +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 canister execution environment, you would run the following command: + +``` bash +dfx build --check +``` diff --git a/docs/cli-reference/dfx-cache.md b/docs/cli-reference/dfx-cache.md new file mode 100644 index 0000000000..329a167c79 --- /dev/null +++ b/docs/cli-reference/dfx-cache.md @@ -0,0 +1,157 @@ +# dfx cache + +Use the `dfx cache` command with flags and subcommands to manage the `dfx` version cache. + +The basic syntax for running `dfx cache` commands is: + +``` bash +dfx cache [subcommand] [flag] +``` + +Depending on the `dfx cache` subcommand you specify, additional arguments, options, and flags might apply. For reference information and examples that illustrate using `dfx cache` commands, select an appropriate command. + +| Command | Description | +|----------------------------|-------------------------------------------------------------------------------| +| [`delete`](#delete) | Deletes the specified version of `dfx` from the local cache. | +| `help` | Displays usage information message for a specified subcommand. | +| [`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. | + +To view usage information for a specific subcommand, specify the subcommand and the `--help` flag. For example, to see usage information for `dfx cache delete`, you can run the following command: + +``` bash +dfx cache delete --help +``` + +## dfx cache delete + +Use the `dfx cache delete` command to delete a specified version of `dfx` from the version cache on the local computer. + +### Basic usage + +``` bash +dfx cache delete [version] [flag] +``` + +### Flags + +You can use the following optional flags with the `dfx cache delete` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Arguments + +You can specify the following argument for the `dfx cache delete` command. + +| Command | Description | +|-----------|--------------------------------------------------------------------| +| `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 `dfx` that you no longer want to use. For example, you can run the following command to delete `dfx` version `0.6.2`: + +``` bash +dfx cache delete 0.6.2 +``` + +## dfx cache install + +Use the `dfx cache install` command to install `dfx` using the version currently found in the `dfx` cache. + +### Basic usage + +``` bash +dfx cache install [flag] +``` + +### Flags + +You can use the following optional flags with the `dfx cache install` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### 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`: + +``` bash +dfx cache install +``` + +## dfx cache list + +Use the `dfx cache list` command to list the `dfx` versions you have currently installed and used in projects. + +If you have multiple versions of `dfx` installed, the cache list displays an asterisk (\*) to indicate the currently active version. + +### Basic usage + +``` bash +dfx cache list [flag] +``` + +### Flags + +You can use the following optional flags with the `dfx cache list` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Examples + +You can use the `dfx cache list` command to list the `dfx` versions you have currently installed and used in projects. For example, you can run the following command to list versions of `dfx` found in the cache: + +``` bash +dfx cache list +``` + +This command displays the list of `dfx` versions found similar to the following: + +``` bash +0.6.4 * +0.6.3 +0.6.0 +``` + +## dfx cache show + +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 + +``` bash +dfx cache show [flag] +``` + +### Flags + +You can use the following optional flags with the `dfx cache show` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Examples + +You can use the `dfx cache show` command to display the path to the cache used by the `dfx` version you are currently using: + +``` bash +dfx cache show +``` + +This command displays the path to the cache used by the `dfx` version you are currently using: + +``` bash +/Users/pubs/.cache/dfinity/versions/0.6.4 +``` diff --git a/docs/cli-reference/dfx-canister.md b/docs/cli-reference/dfx-canister.md new file mode 100644 index 0000000000..cd42b8f6d9 --- /dev/null +++ b/docs/cli-reference/dfx-canister.md @@ -0,0 +1,768 @@ +# dfx canister + +Use the `dfx canister` command with flags and subcommands to manage canister operations and interaction with the {platform} or the local canister execution 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. + +The basic syntax for running `dfx canister` commands is: + +``` bash +dfx canister [subcommand] [flag] +``` + +Depending on the `dfx canister` subcommand you specify, additional arguments, options, and flags might apply or be required. To view usage information for a specific `dfx canister` subcommand, specify the subcommand and the `--help` flag. For example, to see usage information for `dfx canister call`, you can run the following command: + +``` bash +dfx canister call --help +``` + +For reference information and examples that illustrate using `dfx canister` commands, select an appropriate command. + +| Command | Description | +|---------------------------------------|---------------------------| +| [`call`](#dfx-canister-call) | Calls a specified method on a deployed | +| [`create`](#dfx-canister-create) | Creates a new "empty" canister by registering a canister identifier on the {platform} or the local canister execution environment.| +| [`delete`](#dfx-canister-delete) | Deletes a currently stopped canister. | +| `help` | Displays usage information message for a specified subcommand. | +| [`id`](#dfx-canister-id) | Displays the identifier for a canister. | +| [`install`](#dfx-canister-install) | Installs compiled code as a canister on the {platform} or the local canister execution environment. | +| [`request-status`](#dfx-canister-request-status) | Requests the status of a call to a canister. | +| [`set-controller`](#dfx-canister-set-controller) | Specifies the identity name or principal to use as the new controller for a specified canister on the {platform}.| +| [`send`](#dfx-canister-send) | Send a previously-signed `message.json` to a specified canister identifier. For example, if you want to send a message that calls the network nervous system (NNS) governance canister to manage neurons, you might want to separate message signing from message delivery for security reasons.| +| [`sign`](#dfx-canister-send) | Create a signed `message.json` file before making a call to a specified canister identifier. For example, if you want to send a message that calls the network nervous system (NNS) governance canister to manage neurons, you might want to separate message signing from message delivery for security reasons. | +| [`start`](#dfx-canister-start) | Restarts a stopped canister. | +| [`status`](#dfx-canister-status) | Requests the running status of a canister.| +| [`stop`](#dfx-canister-stop) | Stops a currently running canister.| + +## Overriding the default deployment environment + +By default, `dfx canister` commands run on the local canister execution environment specified in the `dfx.json` file. If you want to send a `dfx canister` subcommand to the {platform} or a testnet 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 canister execution environment, you can run the following command: + +``` bash +dfx canister create --all +``` + +If you want to register unique canister identifiers for the same project on the {platform}, you can run the following command: + +``` bash +dfx canister --network ic create --all +``` + +The SDK comes with an alias of `ic`, which is configured to point to the {platform}. You can also pass a URL as a network option, or you can configure additional aliases in `dfx.json` under the `networks` configuration. + +To illustrate, you can call a canister and function running on a testnet using a command similar to the following: + +``` bash +dfx canister --network \http://192.168.3.1:5678 call counter get +``` + +Note that you must specify the `--network` parameter before the canister operation (`create` or `call`) and any additional arguments such as the canister name (`counter`), and function (`get`). + +## dfx canister call + +Use the `dfx canister call` command to call a specified method on a deployed canister. + +### Basic usage + +``` bash +dfx canister call [option] canister_name method_name [argument] [flag] +``` + +### Flags + +You can use the following optional flags with the `dfx canister call` command. + +| Flag | Description | +|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--async` | Enables you to continue without waiting for the result of the call to be returned by polling the local canister execution environment or the {platform}. | +| `-h`, `--help` | Displays usage information. | +| `--query` | Enables you to send a query request to a deployed canister. For best performance, you should use this flag when you explicitly want to use the query method to retrieve information. For information about the difference between query and update calls, see [Canisters include both program and state](../../concepts/canisters-code#canister-state). | +| `--update` | Enables you to send an update request to a deployed canister. By default, canister calls use the update method. | +| `-V`, `--version` | Displays version information. | + +### Options + +You can use the following options with the `dfx canister call` command. + +| Option | Description | +|---------------------|--------------------------------------------------------------------------------------------------------------------------| +| `--output ` | Specifies the output format to use when displaying a method’s return result. The valid values are `idl` and `raw`. | +| `--type ` | Specifies the data format for the argument when making the call using an argument. The valid values are `idl` and `raw`. | + +### Arguments + +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. | +| `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. 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](../../developer-docs/build/languages/candid/candid-intro) (`idl`) syntax for data values. For information about using Candid and its supported types, see [Interact with a service in a terminal](../../developer-docs/build/languages/candid/candid-howto#idl-syntax) and [Supported types](../candid-ref.md). You can use `raw` as the argument type if you want to pass raw bytes to a canister. | + +### 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: + +``` 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 canister execution environment or the {platform} 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: + +``` bash +dfx canister call hello greet --type idl '("Lisa")' +("Hello, Lisa!") + +dfx canister call hello greet '("Lisa")' --type idl +("Hello, Lisa!") +``` + +You can also implicitly use the IDL by running a command similar to the following: + +``` bash +dfx canister call hello greet '("Lisa")' +("Hello, Lisa!") +``` + +To specify multiple arguments using the IDL syntax, use commas between the arguments. For example: + +``` bash +dfx canister call contacts insert '("Amy Lu","01 916-335-2042")' + +dfx canister call hotel guestroom '("Deluxe Suite",42,true)' +``` + +You can pass raw data in bytes by running a command similar to the following: + +``` bash +dfx canister call hello greet --type raw '4449444c00017103e29883' +``` + +This example uses the raw data type to pass a hexadecimal to the `greet` function of the `hello` canister. + +## dfx canister create + +Use the `dfx canister create` command to register one or more canister identifiers without compiled code. You must be connected to the local canister execution environment or the {platform} 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 subdirectories. + +The first time you run the `dfx canister create` command to register an identifier, your public/private key pair credentials are used to create a `default` user identity. The credentials for the `default` user are migrated from `$HOME/.dfinity/identity/creds.pem` to `$HOME/.config/dfx/identity/default/identity.pem`. + +### Basic usage + +``` bash +dfx canister create [option] [flag] [--all | canister_name] +``` + +### Flags + +You can use the following optional flags with the `dfx canister create` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Options + +You can use the following options with the `dfx canister create` command. + +| Option | Description | +|------------------------------------|------------------------------------------------------------------------------------------------------| +| `--with-cycles ` | Enables you to specify the initial number of cycles in a canister when it is created by your wallet. | + +### Arguments + +You can use the following argument with the `dfx canister create` command. + +| Argument | Description| +|-----------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--all` | Enables you to create multiple canister identifiers at once if you have a project `dfx.json` file that defines multiple canisters. Note that you must specify `--all` or an individual canister name. | +| `canister_name` | Specifies the name of the canister for which you want to register an identifier. If you are not using the `--all` option, the canister name is a required argument and 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 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 run the following command: + +``` bash +dfx canister create my_counter +``` + +You can use the `dfx canister create` command with the `--with-cycles` option to specify the initial balance upon the creation of one canister or all canisters in a project. For example, to specify an initial balance of 8000000000000 cycles for all canisters, run the following command: + +``` bash +dfx canister create --with-cycles 8000000000000 --all +``` + +## dfx canister delete + +Use the `dfx canister delete` command to delete a stopped canister from the local canister execution environment or on the {platform}. + +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 +dfx canister delete [flag] [--all | canister_name] +``` + +### Flags + +You can use the following optional flags with the `dfx canister delete` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Arguments + +You can use the following arguments with the `dfx canister delete` command. + +| Argument | Description | +|-----------------|------------------------------------------------------------------------------------------------------------------------------------| +| `--all` | Deletes all of the canisters configured in the `dfx.json` file. Note that you must specify `--all` or an individual canister name. | +| `canister_name` | Specifies the name of the canister you want to delete. Note that you must specify either a canister name or the `--all` option. | + +### 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` {platform}, you can run the following command: + +``` bash +dfx canister --network=ic delete --all +``` + +## dfx canister id + +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. + +### Basic usage + +``` bash +dfx canister id [flag] canister_name +``` + +### Flags + +You can use the following optional flags with the `dfx canister id` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Arguments + +You can use the following argument with the `dfx canister id` command. + +| Argument | Description | +|-----------------|---------------------------------------------------------------------------------| +| `canister_name` | Specifies the name of the canister for which you want to display an identifier. | + +### 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 +dfx canister id hello_world +``` + +The command displays output similar to the following: + +``` bash +75hes-oqbaa-aaaaa-aaaaa-aaaaa-aaaaa-aaaaa-q +``` + +## dfx canister install + +Use the `dfx canister install` command to install compiled code as a canister on the {platform} or on the local canister execution environment. + +### Basic usage + +``` bash +dfx canister install [flag] [option] [--all | canister_name] +``` + +### Flags + +You can use the following optional flags with the `dfx canister install` command. + +| Flag | Description | +|-------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--async` | Enables you to continue without waiting for the result of the installation to be returned by polling the {platform} or the local canister execution environment. | +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Options + +You can use the following options with the `dfx canister install` command. + +| Option | Description | +|---------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--argument ` | Specifies an argument to pass to the canister during installation. | +| `--argument-type ` | Specifies 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](../../developer-docs/build/languages/candid/candid-intro) (`idl`) syntax for data values. For information about using Candid and its supported types, see [Interact with a service in a terminal](../../developer-docs/build/languages/candid/candid-howto#idl-syntax) and [Supported types](../candid-ref.md). You can use `raw` as the argument type if you want to pass raw bytes to a canister. | +| `-c`, `--compute-allocation ` | Defines a compute allocation—essentially the equivalent of setting a CPU allocation—for canister execution. You can set this value as a percentage in the range of 0 to 100. | +| `--memory-allocation ` | Specifies how much memory the canister is allowed to use in total. You can set this value in the range of 0 to 8MB. | +| `-m`, `--mode ` | Specifies whether you want to `install`, `reinstall`, or `upgrade` canisters. For more information about installation modes and canister management, see [Managing canisters](../../developer-docs/build/project-setup/manage-canisters). | + +### Arguments + +You can use the following arguments with the `dfx canister install` command. + +| Argument | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--all` | Enables you to install multiple canisters at once if you have a project `dfx.json` file that includes multiple canisters. Note that you must specify `--all` or an individual canister name. | +| `canister_name` | Specifies the name of the canister to deploy. If you are not using the `--all` option, 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. | + +### 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 {platform} or on the local canister execution environment. The most common use case is to install all of the canisters by running the following command: + +``` bash +dfx canister install --all +``` + +#### Installing a specific canister + +You can also use the `dfx canister install` command to deploy a specific canister instead of all of the canisters in your project. For example, if you have a project with a `hello_world` canister and a `hello_world_assets` canister but only want to deploy the `hello_world` canister, you can deploy just that the canister by running the following command: + +``` bash +dfx canister install hello_world +``` + +#### Sending an asynchronous request + +If you want to submit a request to install the canister and return a request identifier to check on the status of your request later instead of waiting for the command to complete, you can run a command similar to the following: + +``` bash +dfx canister install hello_world --async +``` + +This command submits a request to install the canister and returns a request identifier similar to the following: + +``` bash +0x58d08e785445dcab4ff090463b9e8b12565a67bf436251d13e308b32b5058608 +``` + +You can then use the request identifier to check the status of the request at a later time, much like a tracking number 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. + +For example, you can specify a testnet URL by running a command similar to the following: + +``` bash +dfx canister --network \http://192.168.3.1:5678 install --all +``` + +Note that you must specify the network parameter before the canister operation (`install`) and before the canister name or `--all` flag. + +#### Allocating message processing + +The `--compute-allocation` options allows you to allocate computing resources as a percentage in the range of 0 to 100 to indicate how often your canister should be scheduled for execution. + +For example, assume you run the following command: + +``` bash +dfx canister install --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 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 canisters use the default setting, processing occurs in a round-robin fashion. + +## dfx canister request-status + +Use the `dfx canister request-status` command to request the status of a specified 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`. + +### Basic usage + +``` bash +dfx canister request-status request_id +``` + +### Flags + +You can use the following optional flags with the `dfx canister request-status` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Arguments + +You can specify the following argument for the `dfx canister request-status` command. + +| 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. | + +### Examples + +You can use the `dfx canister request-status` command to check on the status of a canister state change or to verify that a call was not rejected by running a command similar to the following: + +``` bash +dfx canister request-status 0x58d08e785445dcab4ff090463b9e8b12565a67bf436251d13e308b32b5058608 +``` + +This command displays an error message if the request identifier is invalid or refused by the canister. + +## dfx canister set-controller + +Use the `dfx canister set-controller` command to specify the identity name or principal to use as the new **controller** for a specified canister on the {platform}. A controller identity has special rights to manage the canister it controls. For example, only a controlling identity can be used to install, upgrade, or delete the canister under its control. + +Note that you can specify either a user identity or a canister as a controller. You can also specify the controller identity by using its name or its principal. + +### Basic usage + +``` bash +dfx canister set-controller [flag] canister new-controller +``` + +### Flags + +You can use the following optional flags with the `dfx canister set-controller` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Arguments + +You must use the following arguments with the `dfx canister set-controller` command. + +| Argument | Description | +|--------------------|--------------------------------------------------------------------------------------------------------------------------------------| +| `` | Specifies the canister name or canister identifier to be controlled by the identity you specify using the *new_controller* argument. | +| `` | Specifies the identity name or principal of the controller. | + +### Examples + +You can use the `dfx canister set-controller` command to specify a user or canister as the controlling identity for a specific canister. + +For example, you might create a new identity called `pubsadmin` then run the `dfx canister set-controller` to specify that you want the `pubsadmin` identity to be the controller of the `hello_world` canister by running the following commands: + + dfx identity new pubsadmin + dfx canister set-controller hello_world pubsadmin + +To set the controlling identity using the textual representation of the identity principal, you might run a command similar to the following: + + dfx canister set-controller hello_world wcp5u-pietp-k5jz4-sdaaz-g3x4l-zjzxa-lxnly-fp2mk-j3j77-25qat-pqe + +Although specifying a user identity name or principal is one potential use case, a more common scenario is to specify the wallet canister that you want to use to send cycles to the canister. The following steps illustrate this scenario when you are doing local development. For this example, assume you have created a project called `open_sf` with two canisters deployed on the local canister execution environment. + +1. Create an identity—for example, `sf-controller`—to act as the controller. + + dfx identity new sf-controller + + Creating identity: "sf-controller". + Created identity: "sf-controller". + +2. Make the new identity the active identity. + + dfx identity use sf-controller + + Using identity: "sf-controller". + +3. Generate a wallet canister identifier for the new identity. + + dfx identity get-wallet + + Creating a wallet canister on the local canister execution environment. + r7inp-6aaaa-aaaaa-aaabq-cai + The wallet canister on the the local canister execution environment for user "sf-controller" is "r7inp-6aaaa-aaaaa-aaabq-cai" + +4. Switch the active identity to the current controller of the canister. For example, if the default identity was used to create the canister, you would run the following command: + + dfx identity use default + + Using identity: "default". + +5. Set the controller for a specified canister to use the wallet associated wit the sf-controller identity. + + dfx canister set-controller open_sf_assets r7inp-6aaaa-aaaaa-aaabq-cai + + Set "r7inp-6aaaa-aaaaa-aaabq-cai" as controller of "open_sf_assets". + + You can now use the wallet canister `r7inp-6aaaa-aaaaa-aaabq-cai` to send cycles or add custodians to the `open_sf_assets` canister. + +## dfx canister send + +Use the `dfx canister send` command after signing a message with the `dfx canister sign` 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 create a signed `message.json` file using an air-gapped computer, then use the `dfx canister send` command to deliver the signed message. + +### Basic usage + +``` bash +dfx canister send file_name +``` + +### Flags + +You can use the following optional flags with the `dfx canister request-status` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Arguments + +You can specify the following argument for the `dfx canister send` command. + +| Argument | Description | +|-------------|-----------------------------------------| +| `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 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 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 {platform}. + +### Basic usage + +``` bash +dfx canister sign [flag] [option] canister-name method-name [argument] +``` + +### Flags + +You can use the following optional flags with the `dfx canister sign` command. + +| Flag | Description | +|-------------------|----------------------------------------------------------------------------------------------------------| +| `-h`, `--help` | Displays usage information. | +| `--query` | Sends a query request to a canister. | +| `--update` | Sends an update request to the canister. This is the default method if the `--query` method is not used. | +| `-V`, `--version` | Displays version information. | + +### Options + +You can specify the following options for the `dfx canister sign` command. + + + +### Arguments + +You can specify the following arguments for the `dfx canister sign` 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. | +| `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. 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](../candid-ref.md) (`idl`) syntax for data values. For information about using Candid and its supported types, see [Interact with a service in a terminal](../../developer-docs/build/languages/candid/candid-howto#idl-syntax) and [Supported types](../candid-ref#supported-types). You can use `raw` as the argument type if you want to pass raw bytes. | + +### Examples + +Use the `dfx canister sign` command to create a signed `message.json` file using the principal associated with the identity you created using the Privacy Enhanced Mail (PEM) file by running a command similar to the following: + +`dfx canister --network=ic sign --expire-after=1h rno2w-sqaaa-aaaaa-aaacq-cai create_neurons ‘(“PUBLIC_KEY”)’` + +This command illustrates how to creates a `message.json` file to create neurons on the {platform} 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 to specify the point in time when the 5-minute window for sending the signed message should end. For example, if you set the `--expire-after` option to one hour (`1h`), you must wait at least 55 minutes before you send the generated message and the signature for the message is only valid during the 5-minute window ending in the 60th minute. + +In this example, therefore, you would need to send the message after 55 minutes and before 60 minutes for the message to 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 start + +Use the `dfx canister start` command to restart a stopped canister on the {platform} or the local canister execution 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. + +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 +dfx canister start [flag] [--all | canister_name] +``` + +### Flags + +You can use the following optional flags with the `dfx canister start` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Arguments + +You can use the following arguments with the `dfx canister start` command. + +| Argument | Description | +|-----------------|-----------------------------------------------------------------------------------------------------------------------------------| +| `--all` | Starts all of the canisters configured in the `dfx.json` file. Note that you must specify `--all` or an individual canister name. | +| `canister_name` | Specifies the name of the canister you want to start. Note that you must specify either a canister name or the `--all` option. | + +### 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` {platform}, you can run the following command: + +``` bash +dfx canister --network=ic start --all +``` + +## 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 {platform} or on the local canister execution 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 subdirectories. + +### Basic usage + +``` bash +dfx canister status [flag] [--all | canister_name] +``` + +### Flags + +You can use the following optional flags with the `dfx canister status` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Arguments + +You can use the following arguments with the `dfx canister status` command. + +| Argument | Description | +|-----------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--all` | Returns status information for all of the canisters configured in the `dfx.json` file. Note that you must specify `--all` or an individual canister name. | +| `canister_name` | Specifies the name of the canister you want to return information for. Note that you must specify either a canister name or the `--all` option. | + +### Examples + +You can use the `dfx canister status` command to check the status of a specific canister or all canisters. + +To check the status of the `hello_world` canister, you can run the following command: + +``` bash +dfx canister status hello_world +``` + +To check the status for all of the canisters you have deployed on the `ic` {platform}, you can run the following command: + +``` bash +dfx canister --network=ic status --all +``` + +## dfx canister stop + +Use the `dfx canister stop` command to stop a canister that is currently running on the {platform} or on the local canister execution environment. + +In most cases, you run this command to properly terminate any pending requests as a prerequisite to upgrading 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 subdirectories. + +### Basic usage + +``` bash +dfx canister stop [flag] [--all | canister_name] +``` + +### Flags + +You can use the following optional flags with the `dfx canister stop` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Arguments + +You can use the following arguments with the `dfx canister stop` command. + +| Argument | Description | +|-----------------|----------------------------------------------------------------------------------------------------------------------------------| +| `--all` | Stops all of the canisters configured in the `dfx.json` file. Note that you must specify `--all` or an individual canister name. | +| `canister_name` | Specifies the name of the canister you want to stop. Note that you must specify either a canister name or the `--all` option. | + +### Examples + +You can use the `dfx canister stop` command to start a specific canister or all canisters. + +To stop the `hello_world` canister, you can run the following command: + +``` bash +dfx canister stop hello_world +``` + +To stop all of the canisters you have deployed on the `ic` {platform}, you can run the following command: + +``` bash +dfx canister --network=ic stop --all +``` diff --git a/docs/cli-reference/dfx-config.md b/docs/cli-reference/dfx-config.md new file mode 100644 index 0000000000..dbf928a7c5 --- /dev/null +++ b/docs/cli-reference/dfx-config.md @@ -0,0 +1,66 @@ +# dfx config + +Use the `dfx config` command to view or configure settings in the configuration file for a current project. 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 +dfx config [config_path] [value] [flag] +``` + +## Flags + +You can use the following optional flags with the `dfx config` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +## Options + +You can use the following option with the `dfx config` command. + +| Option | Description | +|------------|-----------------------------------------------------------------------------------------------------------------------------------------------------| +| `--format` | Specifies the format of the configuration file output. By default, the file is displayed using JSON format. The valid values are `json` and `text`. | + +## Arguments + +You can specify the following arguments for the `dfx config` command. + +| Argument | Description | +|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `config_path` | Specifies the name of the configuration option that you want to set or read. You must specify the configuration file option using its period-delineated path to set or read the specific option you want to change or view. If you don’t specify the path to a specific configuration option, the command displays the full configuration file. | +| `value` | Specifies the new value for the option you are changing. If you don’t specify a value, the command returns the current value for the option from the configuration file. | + +## Examples + +You can use the `dfx config` command to change configuration settings such as the location of the default output directory or the name of your main program file. + +For example, to change the default build output directory from `canisters` to `staging`, you can run the following command: + +``` bash +dfx config defaults.build.output "staging/" +``` + +To view the current value for a configuration setting, you can specify the path to the setting in the configuration file without specifying a value. For example: + +``` bash +dfx config defaults.build.output +``` + +The command returns the current value for the configuration option: + +``` bash +"staging/" +``` + +Similarly, you can change the name of the main source file or the port number for the local canister execution environment by running commands similar to the following: + +``` bash +dfx config canisters.hello.main "src/hello_world/hello-main.mo" +dfx config networks.local.bind 127.0.0.1:5050 +``` + +You can also verify your configuration changes by viewing the `dfx.json` configuration file after running the `dfx config` command. diff --git a/docs/cli-reference/dfx-deploy.md b/docs/cli-reference/dfx-deploy.md new file mode 100644 index 0000000000..aac6d1c630 --- /dev/null +++ b/docs/cli-reference/dfx-deploy.md @@ -0,0 +1,74 @@ +# dfx deploy + +Use the `dfx deploy` command to register, build, and deploy a dapp on the local canister execution environment, on the IC or on a specified testnet. 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: + + dfx canister create --all + dfx build + dfx canister install --all + +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 +dfx deploy [flag] [option] [canister_name] +``` + +## Flags + +You can use the following optional flags with the `dfx deploy` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +## Options + +You can use the following options with the `dfx deploy` command. + +| Option | Description | +|------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--network ` | Overrides the environment to connect to. By default, the local canister execution environment is used. | +| `--argument ` | Specifies an argument using Candid syntax to pass to the canister during deployment. Note that this option requires you to define an actor class in the Motoko program. | +| `--with-cycles ` | Enables you to specify the initial number of cycles for a canister in a project. | + +### Arguments + +You can specify the following arguments for the `dfx deploy` command. + +| Argument | Description | +|-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `canister_name` | Specifies the name of the canister you want to register, build, and deploy. Note that the canister name you specify must match at least one name in the `canisters` section of the `dfx.json` configuration file for the project. If you don’t specify a canister name, `dfx deploy` will deploy all canisters defined in the `dfx.json` file. | + +## Examples + +You can use the `dfx deploy` command to deploy all or specific canisters on the local canister execution 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: + +``` bash +dfx deploy hello --network ic-pubs +``` + +To deploy a project on the local canister execution environment and pass a single argument to the installation step, you can run a command similar to the following: + +``` bash +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: + + actor class Greet(name: Text) { + public query func greet() : async Text { + return "Hello, " # name # "!"; + }; + }; + +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: + +``` bash +dfx deploy --with-cycles 8000000000000 hello-assets +``` diff --git a/docs/cli-reference/dfx-envars.md b/docs/cli-reference/dfx-envars.md new file mode 100644 index 0000000000..62a30d80f5 --- /dev/null +++ b/docs/cli-reference/dfx-envars.md @@ -0,0 +1,41 @@ +# Environment variables + +You can configure certain properties for your SDK execution 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: + + export DFX_NETWORK=ic + +## CANISTER_CANDID_PATH\_{canister.name} + +Use environment variables with the `CANISTER_CANDID_PATH` prefix to reference the path to the Candid description file for the canisters that are listed as dependencies in the `dfx.json` file for your project. + +For example, if you have a `whoami_assets` canister that lists `whoami` under the `dependencies` key, you could use the `CANISTER_CANDID_PATH_whoami_assets` 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 + +## 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. + +For example, if you have a `linkedup` project that consists of the `linkedup` and `connectd` canisters, you could use the `CANISTER_ID_linkedup` and `CANISTER_ID_connectd` 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. + +## DFX_CONFIG_ROOT + +Use the `DFX_CONFIG_ROOT` environment variable to specify a different location for storing the `.cache` and `.config` subdirectories for `dfx`. + +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_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. + +## DFX_VERSION + +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://smartcontracts.org/install.sh)" diff --git a/docs/cli-reference/dfx-generate.md b/docs/cli-reference/dfx-generate.md new file mode 100644 index 0000000000..6bbf8cc86c --- /dev/null +++ b/docs/cli-reference/dfx-generate.md @@ -0,0 +1,69 @@ +# dfx generate + +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. + +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. + +The `dfx generate` command looks for the configuration under the `declarations` section of a canister in the `dfx.json` configuration file. + +## Basic usage + +``` bash +dfx generate [canister_name] +``` + +## Flags + +You can use the following optional flags with the `dfx generate` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +## Arguments + +You can specify the following arguments for the `dfx generate` command. + +| Argument | Description | +|-----------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `canister_name` | Specifies the name of the canister for which to generate type declarations. 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. If you don’t specify this argument, `dfx generate` will generate type declarations for all canisters declared in `dfx.json`. | + +## Configuration + +The behavior of `dfx generate` is controlled by the `dfx.json` configuration file. Under `dfx.json` → `canisters` → ``, you can add a `declarations` section. In this section, you can specify the following fields: + +| Field | Description | +|----------------|----------------------------------------------------------------------------------------------------------------------------------------------| +| `output` | Directory to place declarations for the canister. Default is `src/declarations/`. | +| `bindings` | List of languages to generate type declarations. Options are `"js", "ts", "did", "mo"`. Default is `["js", "ts", "did"]`. | +| `env_override` | String that will replace `process.env.{canister_name_uppercase}_CANISTER_ID` in the `src/dfx/assets/language_bindings/canister.js` template. | + +Outputs from `dfx generate`: + +| Language | File | +|------------------|-----------------------------------------| +| `JavaScript(js)` | `index.js` and `.did.js` | +| `TypeScript(ts)` | `.did.ts` | +| `Candid(did)` | `.did` | +| `Motoko(mo)` | `.mo` | + +## Examples + +[This](../_attachments/sample-generate-dfx.json) is a sample output of `dfx generate`. + +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` 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/`. + +``` bash +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. + +``` bash +dfx generate +``` diff --git a/docs/cli-reference/dfx-help.md b/docs/cli-reference/dfx-help.md new file mode 100644 index 0000000000..01555ef93a --- /dev/null +++ b/docs/cli-reference/dfx-help.md @@ -0,0 +1,31 @@ +# dfx help + +Use this command to view usage information for the `dfx` parent command or for any specified subcommand. + +## Basic usage + +``` bash +dfx help [subcommand] +``` + +## Arguments + +You can specify any `dfx` subcommand as an argument to view usage information for that subcommand using the `dfx help` command. + +| Argument | Description | +|--------------|-----------------------------------------------------------------| +| `subcommand` | Specifies the subcommand usage information you want to display. | + +## Examples + +To display the usage information for `dfx`, run the following command: + +``` bash +dfx help +``` + +To display the usage information for `dfx new`, run the following command: + +``` bash +dfx help new +``` diff --git a/docs/cli-reference/dfx-identity.md b/docs/cli-reference/dfx-identity.md new file mode 100644 index 0000000000..9a2f6ef6b2 --- /dev/null +++ b/docs/cli-reference/dfx-identity.md @@ -0,0 +1,408 @@ +# dfx identity + +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 canister execution environment. Creating multiple user identities enables you to test user-based access controls. + +The basic syntax for running `dfx identity` commands is: + +``` bash +dfx identity [subcommand] [flag] +``` + +Depending on the `dfx identity` subcommand you specify, additional arguments, options, and flags might apply or be required. To view usage information for a specific `dfx identity` subcommand, specify the subcommand and the `--help` flag. For example, to see usage information for `dfx identity new`, you can run the following command: + +``` bash +dfx identity new --help +``` + +For reference information and examples that illustrate using `dfx identity` commands, select an appropriate command. + +| Command | Description | +|-------------------------------------------------|---------------------------------------------------------------------------------------------------------------------------| +| [`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). | +| [`import`](#dfx-identity-import) | Creates a new identity by importing a PEM file that contains the key information or security certificate for a principal. | +| [`list`](#dfx-identity-list) | Lists existing identities. | +| [`new`](#dfx-identity-new) | Creates a new identity. | +| [`remove`](#dfx-identity-remove) | Removes an existing identity. | +| [`rename`](#dfx-identity-rename) | Renames an existing identity. | +| [`set-wallet`](#dfx-identity-set-wallet) | Sets the wallet canister identifier to use for your current identity principal. | +| [`use`](#dfx-identity-use) | Specifies the identity to use. | +| [`whoami`](#dfx-identity-whoami) | Displays the name of the current identity user context. | + +## Creating a default identity + +The first time you run the `dfx canister create` command to register an identifier, your public/private key pair credentials are used to create a `default` user identity. The credentials for the `default` user are migrated from `$HOME/.dfinity/identity/creds.pem` to `$HOME/.config/dfx/identity/default/identity.pem`. + +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 + +This command adds a private key for the `ic_admin` user identity in the `~/.config/dfx/identity/ic_admin/identity.pem` file. + +## dfx identity get-principal + +Use the `dfx identity get-principal` command to display the textual representation of a principal associated with the current user identity context. + +If you haven’t created any user identities, you can use this command to display the principal for the `default` user. The textual representation of a principal can be useful for establishing and testing role-based authorization scenarios. + +### Basic usage + +``` bash +dfx identity get-principal [flag] +``` + +### Flags + +You can use the following optional flags with the `dfx identity get-principal` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Example + +If you want to display the textual representation of a principal associated with a specific user identity context, you can run commands similar to the following: + +``` bash +dfx identity use ic_admin +dfx identity get-principal +``` + +In this example, the first command sets the user context to use the `ic_admin` identity. The second command then returns the principal associated with the `ic_admin` identity. + +## dfx identity get-wallet + +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 canister execution 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 + +``` bash +dfx identity get-wallet [flag] +``` + +### Flags + +You can use the following optional flags with the `dfx identity get-wallet` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Example + +If you want to display the canister identifier for the wallet canister associated with your identity, you can run the following command: + +``` bash +dfx identity get-wallet +``` + +To display the canister identifier for the wallet canister associated with your identity on a specific testnet, you might run a command similar to the following: + +``` bash +dfx identity --network=https://192.168.74.4 get-wallet +``` + +## dfx identity import + +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. + +### Basic usage + +``` bash +dfx identity import [options] identity-name pem_file-name +``` + +### Flags + +You can use the following optional flags with the `dfx identity import` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Options + +You can specify the following options for the `dfx identity import` command. + +|Argument|Description| +|--------|-----------| +|`--disable-encryption` |DANGEROUS: By default, PEM files are encrypted with a password when writing them to disk. I you want the convenience of not having to type your password (but at the risk of having your PEM file compromised), you can disable the encryption with this flag.| +|`--force` |If the identity already exists, remove and re-import it.| + +### Examples + +You can use the `dfx identity import` command to import a PEM file that contains the security certificate to use for an identity. For example, you can run the following command to import the `generated-id.pem` file to create the user identity `alice`: + +``` bash +dfx identity import alice generated-id.pem +``` + +The command adds the `generated-id.pem` file to the `~/.config/dfx/identity/alice` directory. + +## dfx identity list + +Use the `dfx identity list` command to display the list of user identities available. When you run this command, the list displays an asterisk (\*) to indicate the currently active user context. You should note that identities are global. They are not confined to a specific project context. Therefore, you can use any identity listed by the `dfx identity list` command in any project. + +### Basic usage + +``` bash +dfx identity list [flag] +``` + +### Flags + +You can use the following optional flags with the `dfx identity list` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Examples + +You can use the `dfx identity list` command to list all of the identities you have currently available and to determine which identity is being used as the currently-active user context for running `dfx` commands. For example, you can run the following command to list the identities available: + +``` bash +dfx identity list +``` + +This command displays the list of identities found similar to the following: + +``` bash +alice_auth +anonymous +bob_standard * +default +ic_admin +``` + +In this example, the `bob_standard` identity is the currently-active user context. After you run this command to determine the active user, you know that any additional `dfx` commands you run are executed using the principal associated with the `bob_standard` identity. + +## dfx identity new + +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. + +### Basic usage + +``` bash +dfx identity new [options] _identity-name_ +``` + +### Flags + +You can use the following optional flags with the `dfx identity new` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Arguments + +You must specify the following argument for the `dfx identity new` command. + +| Argument | Description | +|-------------------|--------------------------------------------------------------------------| +| `` | Specifies the name of the identity to create. This argument is required. | + +### Options + +You can specify the following options for the `+dfx identity new+` command. + +|Argument|Description| +|--------|-----------| +|`--disable-encryption` |DANGEROUS: By default, PEM files are encrypted with a password when writing them to disk. I you want the convenience of not having to type your password (but at the risk of having your PEM file compromised), you can disable the encryption with this flag.| +|`--force` |If the identity already exists, remove and re-import it.| +|`--hsm-key-id ` |A sequence of pairs of hex digits.| +|`--hsm-pkcs11-lib-path ` |The file path to the opensc-pkcs11 library e.g. "/usr/local/lib/opensc-pkcs11.so"| + +### Examples + +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 + +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". + +## dfx identity remove + +Use the `dfx identity remove` command to remove an existing user identity. You should note that the identities you add are global. They are not confined to a specific project context. Therefore, any identity you remove using the `dfx identity remove` command will no longer be available in any project. + +### Basic usage + +``` bash +dfx identity remove [flag] _identity-name_ +``` + +### Flags + +You can use the following optional flags with the `dfx identity remove` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Arguments + +You must specify the following argument for the `dfx identity remove` command. + +| Argument | Description | +|-------------------|--------------------------------------------------------------------------| +| `` | Specifies the name of the identity to remove. This argument is required. | + +### Examples + +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 + +The command displays confirmation that the identity has been removed: + + 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 + +## dfx identity rename + +Use the `dfx identity rename` command to rename an existing user identity. You should note that the identities you add are global. They are not confined to a specific project context. Therefore, any identity you rename using the `dfx identity rename` command is available using the new name in any project. + +### Basic usage + +``` bash +dfx identity rename [flag] _from_identity-name_ _to_identity-name_ +``` + +### Flags + +You can use the following optional flags with the `dfx identity rename` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Arguments + +You must specify the following arguments for the `dfx identity rename` command. + +| Argument | Description | +|------------------------|-------------------------------------------------------------------------------------------| +| `` | Specifies the current name of the identity you want to rename. This argument is required. | +| `` | Specifies the new name of the identity you want to rename. This argument is required. | + +### Example + +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 set-wallet + +Use the `dfx identity set-wallet` command to specify the wallet canister identifier to use for your identity. + +### Basic usage + +``` bash +dfx identity set-wallet [flag] [--canister-name canister-name] +``` + +### Flags + +You can use the following optional flags with the `dfx identity set-wallet` command. + +| 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. | +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Example + +If you use more than one principal for your identity, you might have access to more than one wallet canister identifier. You can use the `dfx identity set-wallet` command to specify the wallet canister identifier to use for a given identity. + +For example, you might store the wallet canister identifier in an environment variable, then invoke the `dfx identity set-wallet` command to use that wallet canister for additional operations by running the following: + + export WALLET_CANISTER_ID=$(dfx identity get-wallet) + dfx identity --network=https://192.168.74.4 set-wallet --canister-name ${WALLET_CANISTER_ID} + +## dfx identity use + +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. + +### Basic usage + +``` bash +dfx identity use [flag] _identity-name_ +``` + +### Flags + +You can use the following optional flags with the `dfx identity use` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Arguments + +You must specify the following argument for the `dfx identity use` command. + +| Argument | Description | +|-------------------|----------------------------------------------------------------------------------------------------------------| +| `` | Specifies the name of the identity you want to make active for subsequent commands. This argument is required. | + +### Examples + +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 + +After running this command, subsequent commands use the credentials and access controls associated with the `ops` user. + +## dfx identity whoami + +Use the `dfx identity whoami` command to display the name of the currently-active user identity context. + +### Basic usage + +``` bash +dfx identity whoami [flag] +``` + +### Flags + +You can use the following optional flags with the `dfx identity whoami` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Example + +If you want to display the name of the currently-active user identity, you can run the following command: + +``` bash +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 diff --git a/docs/cli-reference/dfx-ledger.md b/docs/cli-reference/dfx-ledger.md new file mode 100644 index 0000000000..f9214517e4 --- /dev/null +++ b/docs/cli-reference/dfx-ledger.md @@ -0,0 +1,391 @@ +# dfx ledger + +Use the `dfx ledger` command to interact with the 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. + +The basic syntax for running `dfx ledger` commands is: + +``` bash +dfx ledger [options] [subcommand] +``` + +Depending on the `dfx ledger` subcommand you specify, additional arguments, options, and flags might apply. For reference information and examples that illustrate using `dfx ledger` commands, select an appropriate command. + +| Command | Description | +|---------------------------------------|--------------------------------------------------------------------------------------| +| [`account-id`](#dfx-ledger-account-id) | Prints the selected identity’s Account Identifier. | +| [`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) | +| `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. | + +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: + +`dfx ledger transfer --help` + +## dfx ledger account-id + +Use the `dfx ledger account-id` command to display the account identifier associated with the currently-active identity. Like the textual representation of your developer identity principal, the account identifier is derived from your private key and used to represent your identity in the ledger canister. + +### Basic usage + +``` bash +dfx ledger account-id [flag] +``` + +### Flags + +You can use the following optional flags with the `dfx ledger account-id` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Examples + +If you have created more than one identity, check the identity you are currently using by running the `dfx identity whoami` command or the `dfx identity get-principal` command. You can then check the account identifier for your currently-selected developer identity by running the following command: + +``` bash +dfx ledger account-id +``` + +The command displays output similar to the following: + + 03e3d86f29a069c6f2c5c48e01bc084e4ea18ad02b0eec8fccadf4487183c223 + +## dfx ledger balance + +Use the `dfx ledger balance` command to print your account balance or that of another user. + +### Basic usage + +``` bash +dfx ledger --network ic balance [of] [flag] +``` + +### Flags + +You can use the following optional flags with the `dfx ledger balance` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Arguments + +You can specify the following argument for the `dfx ledger balance` command. + +| Argument | Description | +|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `` | Specify an Account Identifier to get the balance. If this command is not specified, the command returns the balance of ICP tokens for the currently-selected user identity. | + +### 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: + +``` bash +dfx ledger --network ic balance 03e3d86f29a069c6f2c5c48e01bc084e4ea18ad02b0eec8fccadf4487183c223 +``` + +This command displays an ICP amount similar to the following: + + 2.49798000 ICP + +## 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. + +### Basic usage + +``` bash +dfx ledger --network ic create-canister controller [options] [flag] +``` + +### Flags + +You can use the following optional flags with the `dfx ledger create-canister` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Arguments + +You can specify the following argument for the `dfx ledger create-canister` command. + +| Argument | Description | +|----------------|----------------------------------------------------------------------------------| +| `` | Specifies the principal identifier to set as the controller of the new canister. | + +### Options + +You can specify the following argument for the `dfx ledger create-canister` command. + +| 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. | +| `--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. | + +### Examples + +To create a new canister with cycles, transfer ICP tokens from your ledger account by running a command similar to the following: + +``` bash +dfx ledger --network ic create-canister tsqwz-udeik-5migd-ehrev-pvoqv-szx2g-akh5s-fkyqc-zy6q7-snav6-uqe --amount 1.25 +``` + +This command converts the number of ICP tokens you specify for the `--amount` argument into cycles, and associates the cycles with a new canister identifier controlled by the principal you specify. + +In this example, the command converts 1.25 ICP tokens into cycles and specifies the principal identifier for the default identity as the controller of the new canister. + +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" + +You can create a new canister by specifying separate values for ICP tokens and e8s by running a command similar to the following: + +``` bash +dfx ledger --network ic create-canister tsqwz-udeik-5migd-ehrev-pvoqv-szx2g-akh5s-fkyqc-zy6q7-snav6-uqe --icp 3 --e8s 5000 +``` + +## dfx ledger fabricate-cycles + +Use the `dfx ledger fabricate-cycles` add cycles to a canister while developing locally. The cycles are created out of thin air and are not deducted from anywhere. + +### Basic usage + +``` +dfx ledger fabricate-cycles [options] +``` + +### Flags + +You can use the following optional flags with the `dfx ledger fabricate-cycles` command. + +| Flag | Description | +|------|-------------| +|`+-h+`, `+--help+` |Displays usage information. | +|`+-V+`, `+--version+` |Displays version information. | + +### Options + +You can specify the following options for the `dfx ledger fabricate-cycles` command. +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 | +|`--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`| +|`--icp`| Specify ICP as a whole number, helpful for use in conjunction with `--e8s`| +|`--t ` |Specifies the amount of cycles to fabricate in trillion cycles. Only accepts whole numbers.| + +### 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: + +``` +dfx ledger fabricate-cycles --all --amount 8000000000000 +``` + +The command displays output similar to the following: + +``` +Fabricating 8000000000000 cycles onto hello +Fabricated 8000000000000 cycles, updated balance: 11_899_662_119_932 cycles +Fabricating 8000000000000 cycles onto hello_assets +Fabricated 8000000000000 cycles, updated balance: 11_899_075_504_924 cycles +``` + +If you would rather only add the cycles to the canister called 'hello' and don't want to type all the zeros, you can do it like this: + +``` +dfx ledger fabricate-cycles --canister hello --t 8 +``` + +The command displays output similar to the following: + +``` +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 send transaction to the cycles minting canister. This command should only be used if `dfx ledger create-canister` or `dfx ledger top-up` 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_ +``` + +### Flags + +You can use the following optional flags with the `dfx ledger notify` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Arguments + +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`. | + +### 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`. + +``` bash +dfx ledger --network ic notify 75948 tsqwz-udeik-5migd-ehrev-pvoqv-szx2g-akh5s-fkyqc-zy6q7-snav6-uqe +``` + +## dfx ledger top-up + +Use the `dfx ledger top-up` command to top up a canister with cycles minted from ICP tokens. + +### Basic usage + +``` bash +dfx ledger --network ic top-up [options] canister [flag] +``` + +### Flags + +You can use the following optional flags with the `dfx ledger top-up` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Arguments + +You can specify the following argument for the `dfx ledger top-up` command. + +| Argument | Description | +|------------|------------------------------------------------------------------| +| `canister` | Specifies the canister identifier that you would like to top up. | + +### Options + +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. | +| `--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. | + +### 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](../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: + +``` bash +dfx ledger --network ic top-up --icp 1 5a46r-jqaaa-aaaaa-qaadq-cai +``` + +This command displays output similar to the following: + + Transfer sent at BlockHeight: 59482 + Canister was topped up! + +## dfx ledger transfer + +Use the `dfx ledger transfer` command to transfer ICP tokens from your account address in the ledger canister to a destination address. + +### Basic usage + +``` bash +dfx ledger transfer [options] to --memo memo +``` + +### Flags + +You can use the following optional flags with the `dfx ledger transfer` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +### Arguments + +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. | + +### Options + +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. | +| `--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 10000 e8s. | +| `--icp ` | Specifies ICP as a whole number. You can use this option alone or in conjunction with `--e8s`. | +| `--memo ` | Specifies a numeric memo for this transaction. | + +### Examples + +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: + +``` bash +dfx ledger account-id +``` + +This command displays output similar to the following: + + 30e596fd6c5ff5ad7b7d70bbbda1187c833e646c6251464da7f82bc217bba397 + +You can check the balance of this account by running the following command: + +``` bash +dfx ledger --network ic balance +``` + +This command displays output similar to the following: + + 64.89580000 ICP + +Use the `dfx ledger transfer` command to send some of your ICP balance to another known destination using the following command: + +``` bash +dfx ledger --network ic transfer dd81336dbfef5c5870e84b48405c7b229c07ad999fdcacb85b9b9850bd60766f --memo 12345 --icp 1 +``` + +This command displays output similar to the following: + + Transfer sent at BlockHeight: 59513 + +You can then use the `dfx ledger --network ic balance` command to check that your account balance reflects the transaction you just made. diff --git a/docs/cli-reference/dfx-new.md b/docs/cli-reference/dfx-new.md new file mode 100644 index 0000000000..b1e6c330ef --- /dev/null +++ b/docs/cli-reference/dfx-new.md @@ -0,0 +1,46 @@ +# dfx new + +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. + +You can use the `--dry-run` option to preview the directories and files to be created without adding them to the file system. + +## Basic usage + +``` bash +dfx new _project_name_ [flag] +``` + +## Flags + +You can use the following optional flags with the `dfx new` command: + +| Flag | Description | +|-------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--dry-run` | Generates a preview the directories and files to be created for a new project without adding them to the file system. | +| `--frontend` | Installs the template frontend code for the default project canister. The default value for the flag is `true` if `node.js` is currently installed on your local computer. If `node.js` is not currently installed, you can set this flag to `true` to attempt to install `node.js` and the template file when creating the project or you can set the flag to `false` to skip the installation of template frontend code entirely. | +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +## Arguments + +You must 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. | + +## Examples + +You can use `dfx new` to create a new project named `my_social_network` by running the following command: + +``` bash +dfx new my_social_network +``` + +The command creates a new project, including a default project directory structure under the new project name and a Git repository for your project. + +If you want to preview the directories and files to be created without adding them to the file system, you can run the following command: + +``` bash +dfx new my_social_network --dry-run +``` diff --git a/docs/cli-reference/dfx-parent.md b/docs/cli-reference/dfx-parent.md new file mode 100644 index 0000000000..a657ac5507 --- /dev/null +++ b/docs/cli-reference/dfx-parent.md @@ -0,0 +1,99 @@ +# dfx + +The DFINITY command-line execution environment (`dfx`) is the primary tool for creating, deploying, and managing the dapps you develop for the IC. + +Use the `dfx` parent command with flags and subcommands to specify the operations you want to perform with or without optional arguments. + +## Basic usage + +``` bash +dfx [option] [subcommand] [flag] +``` + +## Flags + +You can use the following optional flags with the `dfx` parent command or with any of the `dfx` subcommands. + +| Flag | Description | +|----------------------|-------------------------------------------------| +| `-h`, `--help` | Displays usage information. | +| ` -q`, `--quiet` | Suppresses informational messages. | +| `-v`, `--verbose` | Displays detailed information about operations. | +| `-V`, `--version` | Displays version information. | + +## Options + +You can use the following options with the `dfx` command. + +| Option | Description | +|--------------------------------|-------------------------------------------------| +| `-- 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.| + + +## Subcommands + +Use the following subcommands to specify the operation you want to perform or to view usage information for a specific command. + +For reference information and examples, select an appropriate subcommand. + +| Command | Description | +|--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| [`build`](dfx-build) | Builds canister output from the source code in your project. | +| [`cache`](dfx-cache) | Manages the `dfx` cache on the local computer. | +| [`canister`](dfx-canister) | Manages deployed canisters . | +| [`config`](dfx-config) | Sets or changes configuration options for your current project. | +| [`deploy`](dfx-deploy) | Deploys all or a specific canister from the code in your project. By default, all canisters are deployed. | +| [`help`](dfx-help) | Displays usage information for a specified subcommand. | +| [`identity`](dfx-identity) | Enables you to create and manage the identities used to communicate with the IC. | +| [`ledger`](dfx-ledger) | Enables you to interact with accounts in the ledger canister running on the Internet Computer. | +| [`new`](dfx-new) | Creates a new project. | +| [`ping`](dfx-ping) | Sends a response request to the IC or the local canister execution environment to determine network connectivity. If the connection is successful, a status reply is returned. | +| [`replica`](dfx-replica) | Starts a local canister execution environment. | +| [`start`](dfx-start) | Starts the local canister execution environment a web server for the current project. | +| [`stop`](dfx-stop) | Stops the local canister execution environment. | +| [`upgrade`](dfx-upgrade) | Upgrades the version of `dfx` installed on the local computer to the latest version available. | +| [`dfx wallet`](dfx-wallet) | Enables you to manage cycles, controllers, custodians, and addresses for the default cycles wallet associated with the currently-selected identity. | + +## Examples + +You can use the `dfx` parent command to display usage information or version information. For example, to display information about the version of `dfx` you currently have installed, you can run the following command: + +``` bash +dfx --version +``` + +To view usage information for a specific subcommand, specify the subcommand and the `--help` flag. For example, to see usage information for `dfx build`, you can run the following command: + +``` bash +dfx build --help +``` + +### Using logging options + +You can use the `--verbose` and `--quiet` flags to increment or decrement the logging level. If you don’t specify any logging level, CRITICAL, ERROR, WARNING, and INFO messages are logged by default. Specifying one verbose flag (`-v`) increases the log level to include DEBUG messages. Specifying two verbose flags (`-vv`)increases the logging level to include both DEBUG and TRACE messages. + +Adding a `--quiet` flag decreases the logging level. For example, to remove all messages, you can run a command similar the following: + +``` bash +dfx -qqqq build +``` + +Keep in mind that using TRACE level logging (`--vv`) generates a lot of log messages that can affect performance and should only be used when required for troubleshooting or analysis. + +To output log messages to a file named `newlog.txt` and display the messages on your terminal when creating a new project, you can run a command similar to the following: + +``` bash +dfx --log tee --logfile newlog.txt new hello_world +``` + +### Specifying a user identity + +If you create user identities with the `dfx identity new` command, you can then use the `--identity` comment-line option to change the user context when running other `dfx` commands. + +In the most common use case, you use the `--identity` option to call specific canister functions to test access controls 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 --identity devops canister call accounts modify_profile '("Kris Smith")' diff --git a/docs/cli-reference/dfx-ping.md b/docs/cli-reference/dfx-ping.md new file mode 100644 index 0000000000..aeae3a7495 --- /dev/null +++ b/docs/cli-reference/dfx-ping.md @@ -0,0 +1,42 @@ +# dfx ping + +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. + +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 +dfx ping [provider] [flag] +``` + +## Flags + +You can use the following optional flags with the `dfx ping` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +## Arguments + +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. | + +## 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: + +``` bash +dfx ping https://testgw.dfinity.network +``` + +If the IC is running on the specified network provider address, the command returns output similar to the following: + + { + "ic_api_version": "0.8" + } diff --git a/docs/cli-reference/dfx-replica.md b/docs/cli-reference/dfx-replica.md new file mode 100644 index 0000000000..5e0d6663c5 --- /dev/null +++ b/docs/cli-reference/dfx-replica.md @@ -0,0 +1,36 @@ +# dfx replica + +Use the `dfx replica` command to start a local canister execution environment (without a web server). This command enables you to deploy canisters locally and to test your dapps during development. + +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 +dfx replica [option] [flag] +``` + +## Flags + +You can use the following optional flags with the `dfx replica` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +## Options + +You can use the following option with the `dfx replica` command. + +| Option | Description | +|---------------|-------------------------------------------------------------------------------| +| `--port port` | Specifies the port the local canister execution environment should listen to. | + +## Examples + +You can start the local canister execution environment by running the following command: + +``` bash +dfx replica +``` diff --git a/docs/cli-reference/dfx-start.md b/docs/cli-reference/dfx-start.md new file mode 100644 index 0000000000..f0554d2741 --- /dev/null +++ b/docs/cli-reference/dfx-start.md @@ -0,0 +1,56 @@ +# dfx start + +Use the `dfx start` command to start a local canister execution environment and web server processes for the current project. This command enables you to deploy canisters to the local canister execution environment to test your dapps during development. + +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 +dfx start [option] [flag] +``` + +## Flags + +You can use the following optional flags with the `dfx start` command. + +| Flag | Description | +|-------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--background` | Starts the local canister execution environment and web server processes in the background and waits for a reply before returning to the shell. | +| `--clean` | Starts the local canister execution 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. | +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +## Options + +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 is `127.0.0.1:8000`. | + +## Examples + +You can start the local canister execution environment and web server processes in the current shell by running the following command: + +``` bash +dfx start +``` + +If you start the local canister execution environment in the current shell, you need to open a new terminal shell to run additional commands. Alternatively, you can start the local canister execution environment in the background by running the following command: + +``` bash +dfx start --background +``` + +If you run the local canister execution environment in the background, however, be sure to stop the local canister execution environment before uninstalling or reinstalling the `dfx` execution environment by running the following command: + +``` bash +dfx stop +``` + +You can view the current process identifier (`pid`) for the local canister execution environment process started by `dfx` by running the following command: + +``` bash +more .dfx/pid +``` diff --git a/docs/cli-reference/dfx-stop.md b/docs/cli-reference/dfx-stop.md new file mode 100644 index 0000000000..7d5d00e98d --- /dev/null +++ b/docs/cli-reference/dfx-stop.md @@ -0,0 +1,48 @@ +# dfx stop + +Use the `dfx stop` command to stop the local canister execution 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. + +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 +dfx stop [flag] +``` + +## Flags + +You can use the following optional flags with the `dfx stop` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +## Examples + +You can stop the local canister execution environment processes that are running in the background by changing to a project directory then running the following command: + +``` bash +dfx stop +``` + +If the local canister execution environment is running in a current shell rather than in the background, open a new terminal shell, change to a project directory, then run the `dfx stop` command. + +The current process identifier (`pid`) for the canister execution environment process started by `dfx` is recorded in the `.dfx/pid` file. You can view the process identifier before running the `dfx stop` command by running the following command: + +``` bash +more .dfx/pid +``` + +This command displays a process identifier similar to the following: + +``` bash +1896 +``` + +If you are still having trouble with a persistent service running after attempting to stop, you can terminate all running jobs with: + +``` bash +killall dfx replica +``` diff --git a/docs/cli-reference/dfx-upgrade.md b/docs/cli-reference/dfx-upgrade.md new file mode 100644 index 0000000000..7fd9605344 --- /dev/null +++ b/docs/cli-reference/dfx-upgrade.md @@ -0,0 +1,42 @@ +# dfx upgrade + +Use the `dfx upgrade` command to upgrade the SDK components running on your local computer. This command checks the version of the SDK that you have currently installed against the latest publicly-available version specified in the `manifest.json` file. If an older version of the SDK is detected locally, the `dfx upgrade` command automatically fetches the latest version from the CDN. + +## Basic usage + +``` bash +dfx upgrade [flag] [option] +``` + +## Flags + +You can use the following optional flags with the `dfx upgrade` command. + +| Flag | Description | +|-------------------|-------------------------------| +| `-h`, `--help` | Displays usage information. | +| `-V`, `--version` | Displays version information. | + +## Options + +You can use the following option with the `dfx upgrade` command. + +| Option | Description | +|-------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `--current-version ` | Specifies the version you want to identify as the current version. This option enables you to override the version of the software currently identified as the latest version with the version you pass on the command-line. | + +## Examples + +You can upgrade the version of the SDK that you have currently installed by running the following command: + +``` bash +dfx upgrade +``` + +This command checks the version of `dfx` you have currently installed and the latest version available published on the SDK website in a manifest file. If a newer version of `dfx` is available, the command automatically downloads and installs the latest version. + +``` bash +Current version: 0.6.8 +Fetching manifest \https://smartcontracts.org/manifest.json +Already up to date +``` diff --git a/docs/cli-reference/dfx-wallet.md b/docs/cli-reference/dfx-wallet.md new file mode 100644 index 0000000000..c492532f78 --- /dev/null +++ b/docs/cli-reference/dfx-wallet.md @@ -0,0 +1,515 @@ +# dfx wallet + +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: + + +```bash +dfx wallet [option] [flag] +``` + +Depending on the `dfx wallet` subcommand you specify, additional arguments, options, and flags might apply or be required. +To view usage information for a specific `dfx wallet` subcommand, specify the subcommand and the `--help` flag. +For example, to see usage information for `dfx wallet send`, you can run the following command: + +```bash +dfx wallet send --help +``` + +For reference information and examples that illustrate using `dfx wallet` commands, select an appropriate command. + + +|Command |Description +---------|----------------------------------- +|[`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| +|[`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). +|[`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 cycles wallet using the destination wallet canister ID. +|[`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. + + +## Using your wallet + +After you have used the `dfx identity deploy-wallet` command to create a cycles wallet canister tied to an identity, you can use `dfx wallet` commands to modify your cycles wallet settings, send cycles to other cycles wallets, and add or remove controllers and custodians. + +## 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: + +* Rename the cycles wallet. + +* Add entries to the address book. + +* Add and remove controllers. + +* Authorize and deauthorize custodians. + +A controller is also a custodian and can perform the following actions associated with that role: + +* Access wallet information. + +* Send cycles. + +* Forward calls. + +* Create canisters. + + +### Basic usage + + +``` +dfx wallet add-controller [option] [flag] +``` + +### Flags + +You can use the following optional flags with the `dfx wallet add-controller` command. + + +|Flag |Description | +------|--------------- +|`-h`, `--help` |Displays usage information. +|`-V`, `--version` |Displays version information. + +### Options + +You can use the following options with the `dfx canister call` command. + + +|Option |Description| +--------|------------| +|`--network ` |Specifies the environment (e.g., {platform} or testnet) of the controller you want to add. + +### Arguments + +You can specify the following arguments for the `dfx wallet add-controller` command. + + +|Argument |Description +----------|------------- +|`controller` |Specifies the principal of the controller to add to the wallet. + +### Examples + +You can use the `dfx wallet add-controller` command to add a controller to your wallet. If the controller you want to add is on a different environment, specify it using the `--network` option. For example: + + +``` +dfx wallet --network=https://192.168.74.4 add-controller hpff-grjfd-tg7cj-hfeuj-olrjd-vbego-lpcax-ou5ld-oh7kr-kl9kt-yae +``` + +## 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. + +### Basic usage + +``` +dfx wallet addresses +``` + +### Flags + +You can use the following optional flags with the `dfx wallet add-controller` command. + + +|Flag |Description +-------|-------------- +|`-h`, `--help` |Displays usage information. +|`-V`, `--version` |Displays version information. + + +### Examples + +You can use the `dfx wallet addresses` command to retrieve information on the addresses in your wallet's address book. For example: + + +``` +dfx wallet addresses +Id: hpff-grjfd-tg7cj-hfeuj-olrjd-vbego-lpcax-ou5ld-oh7kr-kl9kt-yae, Kind: Unknown, Role: Controller, Name: ic_admin. +Id: e7ptl-4x43t-zxcvh-n6s6c-k2dre-doy7l-bbo6h-ok8ik-msiz3-eoxhl-6qe, Kind: Unknown, Role: Custodian, Name: alice_auth. +``` + +## dfx wallet authorize + +Use the `dfx wallet authorize` command to authorize a custodian for the wallet. An identity assigned the role of custodian can perform the following actions on the cycles wallet: + +* Access wallet information. + +* Send cycles. + +* Forward calls. + +* Create canisters. + +### Basic usage + + +``` +dfx wallet authorize [flag] +``` + +## Flags + +You can use the following optional flags with the `dfx wallet authorize` command. + + +|Flag |Description +-------|------- +|`-h`, `--help` |Displays usage information. +|`-V`, `--version` |Displays version information. + +### Arguments + +Use the following necessary argument with the `dfx wallet authorize` command. + +|Argument |Description +----------|-------- +|`` | Specify the principal of the identity you would like to add as a custodian to the selected identity's cycles wallet. + +### Example + +For example, to add alice_auth as a custodian, specify her principal in the following command: + +``` +dfx wallet authorize dheus-mqf6t-xafkj-d3tuo-gh4ng-7t2kn-7ikxy-vvwad-dfpgu-em25m-2ae +``` + +## dfx wallet balance + +Use the `dfx wallet balance` command to display the balance of the cycles wallet of the selected identity. + +### Basic usage + + +``` +dfx wallet balance +``` + +### Flags + +You can use the following optional flags with the `dfx wallet balance` command. + +|Flag |Description +-------|--------- +|`-h`, `--help` |Displays usage information. +|`-V`, `--version` |Displays version information. + +### Examples + +Check the balance of the selected identity's cycles wallet. + +``` +dfx wallet balance +``` + +This command displays the number of cycles in your cycles wallet. For example: + +``` +89000000000000 cycles. +``` + +## dfx wallet controllers + +Use the `dfx wallet controllers` command to list the principals of the identities that are controllers of the selected identity's cycles wallet. + +### Basic usage + + +``` +dfx wallet controllers +``` + +### Flags + +You can use the following optional flags with the `dfx wallet controllers` command. + +|Flag |Description +|`-h`, `--help` |Displays usage information. +|`-V`, `--version` |Displays version information. + + +### Examples + +List the controllers of your selected identity's cycles wallet. + + +``` +dfx wallet controllers +``` + +The information returned should look similar to the following if there are two controllers: + +``` +dheus-mqf6t-xafkj-d3tuo-gh4ng-7t2kn-7ikxy-vvwad-dfpgu-em25m-2ae +hpnmi-qgxsv-tgecj-hmjyn-gmfft-vbego-lpcax-ou4ld-oh7kr-l3nu2-yae +``` + +## dfx wallet custodians + +Use the `dfx wallet custodians` command to list the principals of the identities that are custodians of the selected identity's cycles wallet. Identities that are added as controllers are also listed as custodians. + +### Basic usage + + +``` +dfx wallet custodians +``` + +### Flags + +You can use the following optional flags with the `dfx wallet custodians` command. + +|Flag |Description +-------|------------ +|`-h`, `--help` |Displays usage information. + + +### Examples + +List the custodians of your selected identity's cycles wallet. + + +``` +dfx wallet custodians +``` + +The information returned should look similar to the following if there are two custodians: + +``` +dheus-mqf6t-xafkj-d3tuo-gh4ng-7t2kn-7ikxy-vvwad-dfpgu-em25m-2ae +hpnmi-qgxsv-tgecj-hmjyn-gmfft-vbego-lpcax-ou4ld-oh7kr-l3nu2-yae +``` + + +## dfx wallet deauthorize + +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. + +### Basic usage + + +``` +dfx wallet deauthorize [flag] +``` + +### Flags + +You can use the following optional flags with the `dfx wallet deauthorize` command. + + +|Flag |Description +----------|-------------- +|`-h`, `--help` |Displays usage information. +|`-V`, `--version` |Displays version information. + +### Arguments + +Use the following necessary argument with the `dfx wallet deauthorize` command. + + +|Argument |Description +----------|-------------- +|`` | Specify the principal of the custodian you want to remove. + +### Example + +For example, to remove "alice_auth" as a custodian, specify her principal in the following command: + + +``` +dfx wallet deauthorize dheus-mqf6t-xafkj-d3tuo-gh4ng-7t2kn-7ikxy-vvwad-dfpgu-em25m-2ae +``` + +## dfx wallet name + +Use the `dfx wallet name` command to display the name of the selected identity's cycles wallet if it has been set using the `dfx wallet set-name` command. + +### Basic usage + + +``` +dfx wallet name [flag] +``` + +### Flags + +You can use the following optional flags with the `dfx wallet name` command. + +|Flag |Description +-------|------------- +|`-h`, `--help` |Displays usage information. +|`-V`, `--version` |Displays version information. + +### Example + +If you have named your cycles wallet "Terrances_wallet", then the command would return the following: + +``` +Terrances_wallet +``` + +## dfx wallet remove-controller + +Use the `dfx wallet remove-controller` command to remove a controller of your selected identity's cycles wallet. + +### Basic usage + + +``` +dfx wallet remove-controller [flag] +``` + +### Flags + +You can use the following optional flags with the `dfx wallet remove-controller` command. + +|Flag |Description +-----------|---------- +|`-h`, `--help` |Displays usage information. +|`-V`, `--version` |Displays version information. + + +### Arguments + +Use the following necessary argument with the `dfx wallet remove-controller` command. + +|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: + + +``` +dfx wallet remove-controller dheus-mqf6t-xafkj-d3tuo-gh4ng-7t2kn-7ikxy-vvwad-dfpgu-em25m-2ae +``` + +## dfx wallet send + +Use the `dfx wallet send` command to send cycles from the selected identity's cycles wallet to another cycles wallet using the destination cycle wallet's Canister ID. + +### Basic usage + + +``` +dfx wallet [network] send [flag] +``` + +### Flags + +You can use the following optional flags with the `dfx wallet send` command. + + +|Flag |Description +-----------|---------- +|`-h`, `--help` |Displays usage information. +|`-V`, `--version` |Displays version information. + +### Options + +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 canister execution 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 + +You must specify the following arguments for the `dfx wallet send` command. + +|Argument |Description +-----------|---------- +|`` |Specify the destination cycle wallet 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: + + +``` +dfx wallet send r7inp-6aaaa-aaaaa-aaabq-cai 2000000000 +``` + +## dfx wallet set-name + +Use the `dfx wallet set-name` command to assign a name to the selected identity's cycles wallet. + +### Basic usage + +``` + dfx wallet set-name [flag] +``` + +### Arguments + +You must specify the following arguments for the `dfx wallet set-name` command. + +|Argument |Description +--------|------------ +|`` |Specify a name for the cycles wallet. + + +### Flags + +You can use the following optional flags with the `dfx wallet set-name` command. + +|Flag |Description +-------|----------- +|`-h`, `--help` |Displays usage information. +|`-V`, `--version` |Displays version information. + + +### Example + +If you want to set the name of the current identity's cycles wallet to "Terrances_wallet" you can run the following command: + + +``` +dfx wallet set-name Terrances_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. + +### Basic usage + + +``` + dfx wallet upgrade [flag] +``` + +### Flags + +You can use the following optional flags with the `dfx wallet upgrade` command. + +|Flag |Description +-------|------------ +|`-h`, `--help` |Displays usage information. +|`-V`, `--version` |Displays version information. + +### Example +To upgrade the Wasm module to the latest version, run the following command: + +``` +dfx wallet upgrade +``` diff --git a/docs/cli-reference/index.md b/docs/cli-reference/index.md new file mode 100644 index 0000000000..9b74950163 --- /dev/null +++ b/docs/cli-reference/index.md @@ -0,0 +1,49 @@ +# Command-line reference + +The DFINITY command-line execution environment (`dfx`) is the primary tool for creating, deploying, and managing the dapps for the Internet Computer platform. + +You can use the `dfx` parent command with different flags and subcommands to perform different types of operations. + +The basic syntax for running `dfx` commands is: + +``` bash +dfx [option] [subcommand] [flag] +``` + +Depending on the subcommand, the options and flags you specify might apply to the parent command or to a specific subcommand. For example, the flags for enabling or suppressing verbose logging are specified for the `dfx` parent command, then applied to any subcommands. + +When you have the SDK installed, you can use the following commands to specify the operation you want to perform. For reference information and examples that illustrate using these commands, select an appropriate command. + +- [dfx](dfx-parent) + +- [dfx bootstrap](dfx-bootstrap) + +- [dfx build](dfx-build) + +- [dfx cache](dfx-cache) + +- [dfx canister](dfx-canister) + +- [dfx config](dfx-config) + +- [dfx deploy](dfx-deploy) + +- [dfx help](dfx-help) + +- [dfx identity](dfx-identity) + +- [dfx ledger](dfx-ledger) + +- [dfx new](dfx-new) + +- [dfx ping](dfx-ping) + +- [dfx replica](dfx-replica) + +- [dfx start](dfx-start) + +- [dfx stop](dfx-stop) + +- [dfx upgrade](dfx-upgrade) + +- [dfx wallet](dfx-wallet)