Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs(agoric-cli): add agoric run; deprecate beta features #904

Merged
merged 3 commits into from
Jan 8, 2024
Merged

docs(agoric-cli): add agoric run; deprecate beta features #904

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
6a474b2
docs(agoric-cli): add agoric run; deprecate beta features
dckc Dec 7, 2023
2eaaf8b
fixup! docs(agoric-cli): add agoric run; deprecate beta features
dckc Jan 3, 2024
e33b360
Merge branch 'main' into dc-agoric-run
ivanlei Jan 8, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
189 changes: 112 additions & 77 deletions main/guides/agoric-cli/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,59 +1,96 @@
# Agoric CLI Commands
# Agoric CLI Reference

In general, you'll want to issue the Agoric CLI (Command Line Interface) commands in this order:
## agoric help

Displays the Agoric CLI commands and arguments with brief descriptions.

**Usage**:

```sh
agoric [command]
```

By default, lists all commands:

```
cosmos <command...> client for an Agoric Cosmos chain
ibc-setup <command...> set up Inter Blockchain Communication
open [options] launch the Agoric UI
init [options] <project> create a new Dapp directory named <project>
set-defaults [options] <program> <config-dir> update the configuration files for <program> in <config-dir>
ibc-relayer run an Inter Blockchain Communications relayer
install [force-sdk-version] install Dapp dependencies
follow [options] <path-spec...> follow an Agoric Casting leader
run <script> [script-args...] run a script with all your user privileges and some Agoric endowments
deploy [options] [script...] run multiple scripts with all your user privileges against the local Agoric
VM
publish [options] [bundle...] publish a bundle to a Cosmos chain
wallet [options] wallet commands
start [options] [profile] [args...] start an Agoric VM
help [command] display help for command
```

## agoric run

Run a script with all your user privileges and some Agoric endowments.

**Usage**:

1. `agoric init $projectDir`
2. `cd $projectDir`
3. `agoric install`
4. `agoric start` (Usually with `--reset`)
5. `agoric deploy`
6. `agoric open`
```sh
agoric run [options] <script> [script-args...]
```

See also:

- [`agoric run` supports bundling proposal modules with writeCoreProposal](https://github.com/Agoric/agoric-sdk/discussions/8087#discussioncomment-6534378) discussion [#8087](https://github.com/Agoric/agoric-sdk/discussions/8087) 2023-07

## agoric init
## ~~agoric init~~

_Deprecated in favor of [yarn create @agoric/dapp](../getting-started/#creating-your-dapp-from-a-template)_

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I don't know the right verbiage, but it may be worthwhile to say something like:

Suggested change
_Deprecated in favor of [yarn create @agoric/dapp](../getting-started/#creating-your-dapp-from-a-template)_
_Internal implementation for the preferred [yarn create @agoric/dapp](../getting-started/#creating-your-dapp-from-a-template)_

if we removed agoric init, then the yarn create @agoric/dapp form would stop working.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

low priority comment:
I feel like as a dapp developer trying to use agoric docs to learn to write a contract/dapp and how to initialize a project, details of internals aren't important to understand. I'm in favor of deprecated.

Creates a new dapp directory named `<project>` with contents copied from the `dapp-template` argument template.

**Syntax**:
**Usage**:

```
agoric init <optional arguments> <projectName>
agoric init [options] <project>
```
* **projectName**: Name of the new project to initialize.

**Optional arguments**:
- **projectName**: Name of the new project to initialize.

* **--dapp-template &lt;name>**: Use the template specified by `<name>`. If this argument isn't passed, then the default dapp `dapp-fungible-faucet` is used.
* **--dapp-base &lt;base-url>**: The location where the dapp template can be found. If this argument isn't passed, then the default value of `git://github.com/Agoric/` is used.
* **-V**, **--version**: Outputs the version number.
* **--docker-tag &lt;tag>**: Uses the specified tag of any started Docker containers. Defaults to `latest`.
* **--sdk**: Uses the Agoric SDK containing this program.
* **-v**, **--verbose**: Causes the command to be run in verbose mode.
* **-h**, **--help**: Displays help for the command.
**Optional arguments**:

- **--dapp-template &lt;name>**: Use the template specified by `<name>`. If this argument isn't passed, then the default dapp `dapp-fungible-faucet` is used.
- **--dapp-base &lt;base-url>**: The location where the dapp template can be found. If this argument isn't passed, then the default value of `git://github.com/Agoric/` is used.
- **-V**, **--version**: Outputs the version number.
- **--docker-tag &lt;tag>**: Uses the specified tag of any started Docker containers. Defaults to `latest`.
- **--sdk**: Uses the Agoric SDK containing this program.
- **-v**, **--verbose**: Causes the command to be run in verbose mode.
- **-h**, **--help**: Displays help for the command.

**Examples**:

```
agoric init demo
```

Creates a directory named "demo" with contents copied from the default dapp-template *dapp-fungible-faucet*.

Creates a directory named "demo" with contents copied from the default dapp-template _dapp-fungible-faucet_.

```
agoric init my-first-contract --dapp-template dapp-simple-exchange
```

Creates a directory named *my-first-contract* with contents copied from the dapp-template *dapp-simple-exchange*.
Creates a directory named _my-first-contract_ with contents copied from the dapp-template _dapp-simple-exchange_.

```
agoric init my-contract --dapp-template dapp-skeleton --dapp-base file:///home/contracts
```

Creates a directory named *my-contract* with contents copied from a dapp-template named *dapp-skeleton* located under the URL *file:///home/contracts*.
Creates a directory named _my-contract_ with contents copied from a dapp-template named _dapp-skeleton_ located under the URL _file:///home/contracts_.

## agoric install
## ~~agoric install~~

_Deprecated_

Comment on lines +91 to +93
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

agoric install can still be used to change the NPM versions of the sdk packages. Maybe we should rename it "agoric update", but that's an sdk change (which could be combined with a resolutions mechanism for endo). @michaelfig thoughts?

Copy link
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

agoric install can still be used to change the NPM versions of the sdk packages.

I'm not clear on what that means. Care to sketch a sentence or two of documentation?

We don't have a test for this feature, by chance, do we?

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

agoric install <npmtag> is definitely tested and used in tests. It updates all the known agoric dependencies to that npm tag. However I think the functionality is currently overloaded, and it's likely acceptable to not advertise it until we have a more complete story, which also handles the issues of version tearing we've noticed with endo packages.

Installs dapp JavaScript dependencies. This may take a while. You use this instead of established npm install tools. The reason is that there is both an SDK (`--sdk`) and NPM mode. Currently we only support SDK mode, which allows you to link your dapp against the SDK dependencies. This allows you to modify any package in the SDK against the SDK dependencies (and see the changes) without having to register those packages with Yarn or NPM.

Expand All @@ -65,13 +102,30 @@ agoric install <optional arguments>

**Optional arguments**:

* **-V**, **--version**: Outputs the version number.
* **--docker-tag &lt;tag>**: Uses the specified tag of any started Docker containers. Defaults to `latest`.
* **--sdk**: Uses the Agoric SDK containing this program.
* **-v**, **--verbose**: Causes the command to be run in verbose mode.
* **-h**, **--help**: Displays help for the command.
- **-V**, **--version**: Outputs the version number.
- **--docker-tag &lt;tag>**: Uses the specified tag of any started Docker containers. Defaults to `latest`.
- **--sdk**: Uses the Agoric SDK containing this program.
- **-v**, **--verbose**: Causes the command to be run in verbose mode.
- **-h**, **--help**: Displays help for the command.

## agoric start local-chain

**Usage**:

## agoric start
```
agoric start local-chain [portNum] -- [initArgs] - local chain

Options:
--reset clear all VM state before starting
--no-restart do not actually start the VM
--pull for Docker-based VM, pull the image before running
--rebuild rebuild VM dependencies before running
-h, --help display help for command
```

## ~~agoric start~~

_Deprecated: Beta Feature_

Runs an Agoric VM on which contracts can run.

Expand All @@ -83,17 +137,17 @@ agoric start <optional arguments>

**Optional arguments**:

* **profile**: Specifies the environment for the VM. Setting this argument to `testnet` connects the VM to our current testnet. If this argument isn't passed, then the default value of `dev` (representing the development mode) is used.
* **--reset**: Clears all VM state before starting.
* **--pull**: For Docker-based VMs, pulls the images before running.
* **--delay [seconds]**: Accounts for processing time in the simulated chain by delaying each round-trip to it by the specified number of seconds. The default value is `1`, which lets you easily count the number of trips in your head. If this argument isn't passed, then the seconds of delay will be set from the numeric value of the FAKE_CHAIN_DELAY environment variable (or zero if there is no such variable).
* **--inspect [host[:port]]**: Activates inspector on host:port. The default value is "127.0.0.1:9229".
* **--inspect-brk [host[:port]]**: Activates inspector on host:port and breaks at start of script. The default value is "127.0.0.1:9229".
* **-V**, **--version**: Outputs the version number.
* **--docker-tag &lt;tag>**: Uses the specified tag of any started Docker containers. Defaults to `latest`.
* **--sdk**: Uses the Agoric SDK containing this program.
* **-v**, **--verbose**: Causes the command to be run in verbose mode.
* **-h**, **--help**: Displays help for the command.
- **profile**: Specifies the environment for the VM. Setting this argument to `testnet` connects the VM to our current testnet. If this argument isn't passed, then the default value of `dev` (representing the development mode) is used.
- **--reset**: Clears all VM state before starting.
- **--pull**: For Docker-based VMs, pulls the images before running.
- **--delay [seconds]**: Accounts for processing time in the simulated chain by delaying each round-trip to it by the specified number of seconds. The default value is `1`, which lets you easily count the number of trips in your head. If this argument isn't passed, then the seconds of delay will be set from the numeric value of the FAKE_CHAIN_DELAY environment variable (or zero if there is no such variable).
- **--inspect [host[:port]]**: Activates inspector on host:port. The default value is "127.0.0.1:9229".
- **--inspect-brk [host[:port]]**: Activates inspector on host:port and breaks at start of script. The default value is "127.0.0.1:9229".
- **-V**, **--version**: Outputs the version number.
- **--docker-tag &lt;tag>**: Uses the specified tag of any started Docker containers. Defaults to `latest`.
- **--sdk**: Uses the Agoric SDK containing this program.
- **-v**, **--verbose**: Causes the command to be run in verbose mode.
- **-h**, **--help**: Displays help for the command.

**Examples**:

Expand All @@ -103,7 +157,6 @@ agoric start --reset

Restarts the Agoric VM, clearing all existing state before doing so.


```
agoric start --pull
```
Expand All @@ -116,10 +169,11 @@ agoric start --delay 5

Configures a 5 second processing time for each round-trip to the simulated chain.

## agoric deploy
## ~~agoric deploy~~

Runs one or more deployment scripts against the local Agoric VM. You may optionally specify which host and port to connect to the VM on.
_Deprecated: Beta Feature_

Runs one or more deployment scripts against the local Agoric VM. You may optionally specify which host and port to connect to the VM on.

**Syntax**:

Expand All @@ -129,9 +183,8 @@ agoric deploy <optional arguments>

**Optional arguments**:


- **Positional Arguments**:
- `<script...>`: Deployment script(s) to run against the local Agoric instance. You must specify at least one, and may specify more than one.
- `<script...>`: Deployment script(s) to run against the local Agoric instance. You must specify at least one, and may specify more than one.
- **Options**:
- `--hostport <HOST:PORT>`: Host and port on which to connect to the VM.
- `-h`, `--help`: Display help for `deploy` command
Expand All @@ -142,28 +195,30 @@ agoric deploy <optional arguments>
agoric init demo
```

Creates a directory named "demo" with contents copied from the default dapp-template *dapp-fungible-faucet*.

Creates a directory named "demo" with contents copied from the default dapp-template _dapp-fungible-faucet_.

```
agoric init my-first-contract --dapp-template dapp-simple-exchange
```

Creates a directory named *my-first-contract* with contents copied from the dapp-template *dapp-simple-exchange*.
Creates a directory named _my-first-contract_ with contents copied from the dapp-template _dapp-simple-exchange_.

```
agoric init my-contract --dapp-template dapp-skeleton --dapp-base file:///home/contracts
```

Creates a directory named *my-contract* with contents copied from a dapp-template named *dapp-skeleton* located under the URL *file:///home/contracts*.
Creates a directory named _my-contract_ with contents copied from a dapp-template named _dapp-skeleton_ located under the URL _file:///home/contracts_.

- **Examples**:
- Run the specified `deploy.js` scripts against the local Agoric VM.
- `agoric deploy ./contract/deploy.js ./api/deploy.js`
- Run the specified `deploy.js` scripts on VM host 128.7.3.139 and
port 99.
- `agoric deploy --hostport 128.7.3.139:99 ./contract/deploy.js`

## agoric open
## ~~agoric open~~

_Deprecated: Beta Feature_

Launches the Agoric UI. By default, only the UI is shown, not the REPL (Read-Eval-Print-Loop). To show both the UI and REPL, or only the REPL, see the `--repl` optional argument below.

Expand All @@ -180,7 +235,7 @@ agoric open <optional arguments>
- **Options**
- `--hostport <host:port>`: Host and port on which to connect to the VM (default: "127.0.0.1:8000").
- `--no-browser`: Display the UI's URL, but don't open a browser.
- `--repl [yes | only | no]`: Whether to show the Read-Eval-Print loop. Defaults to `yes` if specified (see
- `--repl [yes | only | no]`: Whether to show the Read-Eval-Print loop. Defaults to `yes` if specified (see
Examples below)
- `-h`, `--help`: Display help for `open` command.

Expand All @@ -190,20 +245,20 @@ agoric open <optional arguments>
agoric init demo
```

Creates a directory named "demo" with contents copied from the default dapp-template *dapp-fungible-faucet*.

Creates a directory named "demo" with contents copied from the default dapp-template _dapp-fungible-faucet_.

```
agoric init my-first-contract --dapp-template dapp-simple-exchange
```

Creates a directory named *my-first-contract* with contents copied from the dapp-template *dapp-simple-exchange*.
Creates a directory named _my-first-contract_ with contents copied from the dapp-template _dapp-simple-exchange_.

```
agoric init my-contract --dapp-template dapp-skeleton --dapp-base file:///home/contracts
```

Creates a directory named *my-contract* with contents copied from a dapp-template named *dapp-skeleton* located under the URL *file:///home/contracts*.
Creates a directory named _my-contract_ with contents copied from a dapp-template named _dapp-skeleton_ located under the URL _file:///home/contracts_.

- **Examples**
- Launch only the Agoric UI in a browser
- `agoric open`
Expand All @@ -213,23 +268,3 @@ Creates a directory named *my-contract* with contents copied from a dapp-templat
- `agoric open --repl only`
- Display both the Agoric UI and the REPL in a browser (`--repl` defaults to `yes`).
- `agoric open --repl`

## agoric help

Displays the Agoric CLI commands and arguments with brief descriptions.

**Syntax**:

```
agoric help <optional arguments>
```

**Optional arguments**:

* **-V**, **--version**: Outputs the version number.
* **--docker-tag &lt;tag>**: Uses the specified tag of any started Docker containers. Defaults to `latest`.
* **--sdk**: Uses the Agoric SDK containing this program.
* **-v**, **--verbose**: Causes the command to be run in verbose mode.
* **-h**, **--help**: Displays help for the command.


3 changes: 2 additions & 1 deletion main/guides/getting-started/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -155,7 +155,8 @@ For more examples and ideas, visit:
```
</details>

## Installing the Sample Dapp
## Creating Your Dapp From a Template

Now you'll use yarn to pull down the sample dapp. The sample dapp will be placed in a subfolder named `demo`.

```sh
Expand Down
Loading