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

New commands layout #75

Merged
merged 29 commits into from
Sep 30, 2022
Merged

New commands layout #75

Changes from all commits
Commits
Show all changes
29 commits
Select commit Hold shift + click to select a range
59c2189
first small draft of the commands layout
volovyks Nov 2, 2021
7579dd1
helper commands moved to a separate extensions in doc
volovyks Nov 3, 2021
f3f9a87
commands in proposal renamed
volovyks Nov 3, 2021
9c5c30a
Update docs/NEW_GUIDE_DRAFT.en.md
volovyks Nov 3, 2021
b3733c7
Update docs/NEW_GUIDE_DRAFT.en.md
volovyks Nov 3, 2021
bb5ccaf
NEW-GUIDE updated accoring to the comments
volovyks Nov 4, 2021
d19cdb1
function calls renamed to method calls in doc
volovyks Nov 4, 2021
2b42e8b
new commands proposal refactored
volovyks Nov 4, 2021
6479f32
multiple acc import options added to the doc
volovyks Nov 4, 2021
67c8588
config commands added to the doc
volovyks Nov 4, 2021
1f882db
command structure in doc updated
volovyks Nov 5, 2021
f01617f
network name added as a parameter to manage-connections doc
volovyks Nov 5, 2021
433bf62
CLI UX principles added
volovyks Nov 5, 2021
35a3116
new cli interface md file formatted
volovyks Nov 5, 2021
f94cfdc
paramtere added to new cli interface doc
volovyks Nov 5, 2021
8f025f2
new commands layout updated
volovyks Nov 18, 2021
b77db3d
new commands design update
volovyks Nov 18, 2021
c15bcfe
new commadns design updated
volovyks Nov 18, 2021
87346d5
import-account replaced
volovyks Nov 19, 2021
0aedf98
account added to the tope level of the cli design
volovyks Nov 19, 2021
0e29834
new layout proposal
frol May 7, 2022
c267b9b
Update NEW_NEAR_CLI_INTERFACE.md
frol May 10, 2022
22dc8ea
more extension ideas added
volovyks May 13, 2022
85393f6
Update docs/NEW_NEAR_CLI_INTERFACE.md
volovyks May 16, 2022
f1446fa
Update NEW_NEAR_CLI_INTERFACE.md
frol May 16, 2022
78f0a05
updated `autogenerate-new-keypair` subcommand
frol May 17, 2022
238763d
just updated text formatting
frol May 17, 2022
207485b
moved inspect-storage to the developer extension
frol Jul 12, 2022
76ef27b
extended `add-key` with the parameters to specify the kind of access key
frol Jul 12, 2022
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
201 changes: 201 additions & 0 deletions docs/NEW_NEAR_CLI_INTERFACE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,201 @@
# New NEAR CLI interface

NEAR CLI is built for:
- **NEAR dApp developers**, who build smart-contracts, UIs, and tooling on NEAR.
- **Tech-savvy people** automating their routines.
- **Validators**

NEAR CLI is using extensions to satisfy all groups of users.
- **Core NEAR CLI** commands should be usefull for all groups of users.
- **Extensions** are used by a particular group or several groups of users.
- **Core NEAR CLI** is a single binary, there is no extensions that are installed *by default*.
- Each extension is a separate binary that can be installed and executed from **NEAR CLI**.
- **Core NEAR CLI** extensions system only allows to introduce top-level commands through its design.


NEAR CLI UX principles:
- All altering actions should have a confirmation step with an option to skip confirmation with an explicit command line parameter (e.g. `send` at the end of the command)
- All direct children commands of a single parent command should be aligned (either represent an action or a resource, but never a mix of those on the same hierarchy level): `contract` -> `state` (resource) and `contract` -> `deploy` (action) are not aligned, so it should be either `contract` -> `get-state` + `contract` -> `deploy` or `contract` -> `state` -> `view` + `contract` -> `code` -> `deploy`
BenKurrek marked this conversation as resolved.
Show resolved Hide resolved
- Interactive mode should look like: `command - description`. It will help people to learn the commands.

## Core NEAR CLI commands

```
account
frol marked this conversation as resolved.
Show resolved Hide resolved
- view-account-summary <account-id> network <"mainnet"|"testnet"|...> <now|at-timestamp|at-block-height|at-block-hash>

- create-subaccount <new-account-id> <initial-balance>
(we will treat everything after the first dot in account id as the parent account (transaction signer))
frol marked this conversation as resolved.
Show resolved Hide resolved
- autogenerate-new-keypair
- save-to-keychain network <"mainnet"|"testnet"|...>
- transaction signature options here (see below)
- print-to-terminal network <"mainnet"|"testnet"|...>
- transaction signature options here (see below)
- use-manually-provided-seed-prase "twelve words goes here" network <"mainnet"|"testnet"|...>
- transaction signature options here (see below)
- use-manually-provided-public-key "ed25519:..." network <"mainnet"|"testnet"|...>
- transaction signature options here (see below)

- delete-account <account-id> beneficiary <beneficiary-account-id> network <"mainnet"|"testnet"|...>
- transaction signature options here (see below)

- list-keys <account-id> network <"mainnet"|"testnet"|...> <now|at-timestamp|at-block-height|at-block-hash>

- add-key <account-id>
- grant-full-access
- autogenerate-new-keypair
- save-to-keychain network <"mainnet"|"testnet"|...>
- transaction signature options here (see below)
- print-to-terminal network <"mainnet"|"testnet"|...>
- transaction signature options here (see below)
- use-manually-provided-seed-phrase "twelve words goes here" network <"mainnet"|"testnet"|...>
Copy link

Choose a reason for hiding this comment

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

This is an issue I filled with near-cli. It's bad security practice to use a seed phrase as a CLI arg. So perhaps this should be interactive like a password.

Copy link
Collaborator

Choose a reason for hiding this comment

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

It is both interactive and non-interactive, and again, I don’t expect users to type the command out manually most of the time, so the parameters are there only for reproducibility and integration within scripts, which I don’t see a reason to limit to use params

- transaction signature options here (see below)
- use-manually-provided-public-key "ed25519:..." network <"mainnet"|"testnet"|...>
- transaction signature options here (see below)
- grant-function-call-access --receiver-account-id <account-id> --method-names 'comma,separated,list' --allowance '0.25NEAR'
- (use the same follow-up parameters as for `grant-full-access`)

- delete-key <account-id> <public-key> network <"mainnet"|"testnet"|...>
- transaction signature options here (see below)

- TODO: "import account" (aka "login") commands
```

```
contract
- call-function
- as-read-only <account-id> <function-name> <function-args> network <"mainnet"|"testnet"|...> <now|at-timestamp|at-block-height|at-block-hash>
Copy link

Choose a reason for hiding this comment

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

Why not just view? Even knowing that as-read-only means view I found it confusing and is less intuitive since we use view everywhere else.

near-cli contract call-function as-read-only ...

Is also a bit long. I know you're love for being explicit, but having some aliases here would be nice.

near contract view

As a short cut would be very handy.

Copy link

Choose a reason for hiding this comment

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

To me just saying view might lead some people to think that they're viewing the contract code rather than it being viewing the result of a read-only function.

Copy link

Choose a reason for hiding this comment

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

If you execute a view call and try to invoke a host function like creating a transaction, you will get an error that says it was banned in a view call. So my point is that we use view in our documentation and baked into the runtime, so using it, especially in this context helps people to learn it.

Copy link
Collaborator

Choose a reason for hiding this comment

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

@willemneal If you finish up the whole command, you will see that it does not make any sense to save a few characters:

near-cli contract view zavodil.poolv1.near get_owner_id '{}' network mainnet now
near-cli contract call-function as-read-only zavodil.poolv1.near get_owner_id '{}' network mainnet now

I don't expect anyone to type it out manually as we have interactive mode that guides users through it, and prints out the final command if you want to re-use it later.

contract view makes sense only to victims of near-cli-js naming. Anyone else will be confused and guess that this command will show you the contract, not calling a function. Yet, the good part of this new approach is that you will be able to implement your own extension and call it as near-cli view ... just fine, if you feel you want to have a shortcut.

- as-transaction <account-id> <function-name> <function-args> --prepaid-gas <prepaid-gas> --attached-deposit <deposit-amount> network <"mainnet"|"testnet"|...>
- transaction signature options here (see below)
frol marked this conversation as resolved.
Show resolved Hide resolved

- deploy <account-id> use-file <path-to-wasm-file>

- with-init-call <function-name> <function-args> --prepaid-gas <prepaid-gas> --attached-deposit <deposit-amount>
- transaction signature options here (see below)
- without-init-call
- transaction signature options here (see below)

- download-wasm <account-id> to-folder <path-to-download-folder> network <"mainnet"|"testnet"|...> <now|at-timestamp|at-block-height|at-block-hash>
```
volovyks marked this conversation as resolved.
Show resolved Hide resolved

```
tokens <owner-account-id>
- send-near <receiver-account-id> <amount-in-NEAR> network <"mainnet"|"testnet"|...>
frol marked this conversation as resolved.
Show resolved Hide resolved
- transaction signature options here (see below)

- send-ft <ft-contract-account-id> <receiver-account-id> <amount-in-fungible-tokens> network <"mainnet"|"testnet"|...>
- transaction signature options here (see below)

- send-nft <nft-contract-account-id> <receiver-account-id> <token-id> network <"mainnet"|"testnet"|...>
- transaction signature options here (see below)

- view-near-balance network <"mainnet"|"testnet"|...> <now|at-timestamp|at-block-height|at-block-hash>

- view-ft-balance <ft-contract-account-id> network <"mainnet"|"testnet"|...> <now|at-timestamp|at-block-height|at-block-hash>

- view-nft-assets <nft-contract-account-id> network <"mainnet"|"testnet"|...> <now|at-timestamp|at-block-height|at-block-hash>
```

```
transaction
- view-status <transaction-hash> <signer-account-id> network <"mainnet"|"testnet"|...>

- construct-transaction (TODO: keep the current command structure for now)
```

```
extensions
(WIP)
- explore
- install
- list-installed
- uninstall
```

```
config
(WIP)
- connections
- show-selected
- select <connection-name>
- list
- add <connection-name> <> <network-name> <url1> <url1> <...>
- delete <connection-name>
- cli
- set <parameter> <value>
- get <parameter>
```

```
local-keys
(WIP: maybe merge into the `account` command)
- add-using
- near-wallet
- seed-phrase <seed-phrase>
- ledger
- private-key <private-key>
- generate
```

Transaction signature options:
* `sign-with-keychain`
frol marked this conversation as resolved.
Show resolved Hide resolved
* `sign-with-ledger`
* `sign-with-plaintext-private-key "ed25519:..."`

### Top-level `Core NEAR CLI` flags
```txt
--verbose (print all available error info)
--json (show answer in json format)
--scripting (turn off interactive mode)
```

## Extensions
volovyks marked this conversation as resolved.
Show resolved Hide resolved
Extensions design is a work in progress. They are here mostly to show that we haven't forgotten about particular functionality and that this functionality will not be a part of `Core NEAR CLI`.
frol marked this conversation as resolved.
Show resolved Hide resolved

### `developer` extension
```txt
- dev-deploy-code <wasm-file>
- inspect-storage <account-id> key-prefix <storage-key-prefix> network <"mainnet"|"testnet"|...> <now|at-timestamp|at-block-height|at-block-hash>
- ...
```

### `explorer` extension
```txt
- get-recent-block-hash
- get-transaction-status <transaction-hash>
- get-epoch-status <epoch>
- ...
```

### `transaction-constructor` extension
```txt
- constract-transaction
- sign-transaction-with-private-key
- combine-unsigned-transaction-with-signature
- sign-transaction-with-ledger
- send-signed-transaction
- deserialize-bytes-from-base64
- ...
```

### `staking-for-delegators` extension
```txt
- make-new-stake-proposal
- stake
- unstake
- ...
```

### `validators` extension
```txt
- stake
- validators
- proposals
- ...
```

### Other extensions
- `NFT`
- `FT`
- `lockup`
- `multisig`