Skip to content

docs: improve command descriptions #399

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

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

docs: improve command descriptions #399

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
7ca22b0
docs: consistent command description
fadeev Aug 13, 2025
e147420
descriptions
fadeev Aug 13, 2025
0f6a0b4
Descriptions
fadeev Aug 13, 2025
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
7 changes: 6 additions & 1 deletion packages/commands/src/accounts/create.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,8 +31,13 @@ const main = async (options: CreateAccountOptions) => {

export const createAccountsCommand = new Command("create")
.summary("Create a new account")
.description(
`Generates a new account for the specified chain type.

You can name the account for easier identification; if no name is provided, it defaults to default.`
)
.addOption(
new Option("--type <type>", "Account type").choices(AvailableAccountTypes)
new Option("--type <type>", "Chain type").choices(AvailableAccountTypes)
)
Comment on lines +40 to 41
Copy link
Contributor

Choose a reason for hiding this comment

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

💡 Verification agent

🧩 Analysis chain

Copy looks good; ensure “Chain type” phrasing is consistent repo-wide

This aligns with the broader shift from “Account type” → “Chain type.” Quick scan recommended to ensure no remnants remain in other commands.

Expected: No matches.


---

🏁 Script executed:

```shell
#!/bin/bash
# Check for lingering "Account type" labels in options across the repo
rg -n -C2 -P 'Option\("--type\s*<type>",\s*"Account type"\)'

Length of output: 424

Ensure “Chain type” phrasing is consistent across all account commands

We’ve detected one remaining instance of the old “Account type” label that needs updating for consistency.

• packages/commands/src/accounts/show.ts, line 47
Change

new Option("--type <type>", "Account type").choices(AvailableAccountTypes)

to

new Option("--type <type>", "Chain type").choices(AvailableAccountTypes)
🤖 Prompt for AI Agents 
In packages/commands/src/accounts/create.ts around lines 40-41 the Option
description already uses "Chain type"; ensure consistency by updating
packages/commands/src/accounts/show.ts (around line 47) to replace the outdated
"Account type" description with "Chain type" on the new Option("--type <type>",
...) so both commands use the same phrasing and AvailableAccountTypes choices.

.option("--name <name>", "Account name", DEFAULT_ACCOUNT_NAME)
.action(async (opts) => {
Expand Down
5 changes: 4 additions & 1 deletion packages/commands/src/accounts/delete.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,8 +53,11 @@ const main = async (options: DeleteAccountOptions) => {

export const deleteAccountsCommand = new Command("delete")
.summary("Delete an existing account")
.description(
`Removes an account from the local key store. You must provide both the chain type and account name.`
)
.addOption(
new Option("--type <type>", "Account type").choices(AvailableAccountTypes)
new Option("--type <type>", "Chain type").choices(AvailableAccountTypes)
)
.requiredOption("--name <name>", "Account name")
.action(async (opts) => {
Expand Down
7 changes: 5 additions & 2 deletions packages/commands/src/accounts/import.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,11 +31,14 @@ const main = async (options: ImportAccountOptions) => {
};

export const importAccountsCommand = new Command("import")
.summary("Import an existing account")
.description(
"Import an existing account using either a private key or a mnemonic"
`Adds an account to the local key store using a private key or mnemonic phrase.

You can choose the chain type and give the account a name.`
)
.addOption(
new Option("--type <type>", "Account type").choices(AvailableAccountTypes)
new Option("--type <type>", "Chain type").choices(AvailableAccountTypes)
)
.option("--name <name>", "Account name", DEFAULT_ACCOUNT_NAME)
.addOption(
Expand Down
7 changes: 6 additions & 1 deletion packages/commands/src/accounts/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,12 @@ import { listAccountsCommand } from "./list";
import { showAccountsCommand } from "./show";

export const accountsCommand = new Command("accounts")
.summary("Account management commands")
.summary("Manage accounts for all connected chains")
.description(
`Manages accounts for all connected chains in the ZetaChain CLI. Supports creating new accounts, importing existing ones, listing all accounts, showing details, and deleting accounts.

Accounts are stored locally in the CLI's key management system and can be used across all supported networks.`
)
.addCommand(createAccountsCommand)
.addCommand(deleteAccountsCommand)
.addCommand(importAccountsCommand)
Expand Down
5 changes: 4 additions & 1 deletion packages/commands/src/accounts/list.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,10 @@ const main = (options: ListAccountsOptions): void => {
};

export const listAccountsCommand = new Command("list")
.summary("List all available accounts")
.summary("List all stored accounts")
.description(
`Display all accounts currently stored locally in the CLI key store`
)
.option("--json", "Output in JSON format")
.action((opts) => {
const validated = validateAndParseSchema(opts, listAccountsOptionsSchema, {
Expand Down
5 changes: 4 additions & 1 deletion packages/commands/src/accounts/show.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,10 @@ const main = (options: ShowAccountOptions): void => {
};

export const showAccountsCommand = new Command("show")
.summary("Show details of an existing account")
.summary("View details of a specific account")
.description(
`Show the address, public key, and other details for a specific account. You must provide the chain type and account name.`
)
.addOption(
new Option("--type <type>", "Account type").choices(AvailableAccountTypes)
)
Expand Down
5 changes: 4 additions & 1 deletion packages/commands/src/bitcoin/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,10 @@ import { inscriptionCommand } from "./inscription/";
import { memoCommand } from "./memo/";

export const bitcoinCommand = new Command("bitcoin")
.description("Bitcoin-related commands")
.summary("Deposit BTC and call universal contracts from Bitcoin")
.description(
"Work with Bitcoin to deposit BTC to ZetaChain or call contracts using inscriptions or OP_RETURN memo."
)
.alias("b")
.addCommand(inscriptionCommand)
.addCommand(memoCommand)
Expand Down
3 changes: 3 additions & 0 deletions packages/commands/src/bitcoin/inscription/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,9 @@ import { encodeCommand } from "./encode";

export const inscriptionCommand = new Command("inscription")
.summary("Make a transaction using inscriptions")
.description(
"Use Bitcoin inscriptions to deposit BTC to ZetaChain or call contracts"
)
.alias("i")
.addCommand(callCommand)
.addCommand(depositAndCallCommand)
Expand Down
3 changes: 3 additions & 0 deletions packages/commands/src/bitcoin/memo/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,9 @@ import { depositAndCallCommand } from "./depositAndCall";

export const memoCommand = new Command("memo")
.summary("Make a transaction using a memo (OP_RETURN)")
.description(
"Use OP_RETURN memo to deposit BTC to ZetaChain or call contracts"
)
.alias("m")
.addCommand(callCommand)
.addCommand(depositAndCallCommand)
Expand Down
6 changes: 3 additions & 3 deletions packages/commands/src/evm/call.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -89,9 +89,9 @@ Parameter types: ${stringifiedTypes}
}
};

export const callCommand = new Command("call").summary(
"Call a contract on ZetaChain from an EVM-compatible chain"
);
export const callCommand = new Command("call")
.summary("Call a contract on ZetaChain from an EVM-compatible chain")
.description("Call a contract on ZetaChain from an EVM-compatible chain");

addCommonEvmCommandOptions(callCommand)
.requiredOption(
Expand Down
6 changes: 3 additions & 3 deletions packages/commands/src/evm/deposit.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -85,9 +85,9 @@ const main = async (options: DepositOptions) => {
}
};

export const depositCommand = new Command("deposit").summary(
"Deposit tokens to ZetaChain from an EVM-compatible chain"
);
export const depositCommand = new Command("deposit")
.summary("Deposit tokens to ZetaChain from an EVM-compatible chain")
.description("Deposit tokens to ZetaChain from an EVM-compatible chain");

addCommonEvmCommandOptions(depositCommand)
.requiredOption("--amount <amount>", "Amount of tokens to deposit")
Expand Down
10 changes: 7 additions & 3 deletions packages/commands/src/evm/depositAndCall.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -105,9 +105,13 @@ Parameter types: ${stringifiedTypes}
}
};

export const depositAndCallCommand = new Command("deposit-and-call").summary(
"Deposit tokens and call a contract on ZetaChain from an EVM-compatible chain"
);
export const depositAndCallCommand = new Command("deposit-and-call")
.summary(
"Deposit tokens and call a contract on ZetaChain from an EVM-compatible chain"
)
.description(
"Deposit tokens and call a contract on ZetaChain from an EVM-compatible chain"
);

addCommonEvmCommandOptions(depositAndCallCommand)
.requiredOption("--amount <amount>", "Amount of tokens to deposit")
Expand Down
5 changes: 4 additions & 1 deletion packages/commands/src/evm/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,10 @@ import { depositCommand } from "./deposit";
import { depositAndCallCommand } from "./depositAndCall";

export const evmCommand = new Command("evm")
.summary("EVM commands")
.summary("Deposit tokens and call universal contracts from EVM")
.description(
"Interact from EVM chains: call contracts on ZetaChain or deposit tokens (with or without a call)."
)
.addCommand(callCommand)
.addCommand(depositAndCallCommand)
.addCommand(depositCommand)
Expand Down
3 changes: 2 additions & 1 deletion packages/commands/src/faucet.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -34,7 +34,8 @@ const main = async (options: FaucetOptions) => {

export const faucetCommand = new Command()
.name("faucet")
.description("Request testnet ZETA tokens from the faucet.")
.summary("Request testnet ZETA tokens from the faucet")
.description("Request testnet ZETA tokens from the faucet")
.addOption(
new Option("--address <address>", "Recipient address.").conflicts(["name"])
)
Expand Down
3 changes: 3 additions & 0 deletions packages/commands/src/program.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,9 @@ import { zetachainCommand } from "./zetachain";

export const toolkitCommand = new Command("toolkit")
.summary("Local development environment")
.description(
"ZetaChain Toolkit CLI for local development and cross-chain operations"
)
.helpCommand(false);

toolkitCommand.addCommand(accountsCommand);
Expand Down
18 changes: 8 additions & 10 deletions packages/commands/src/query/balances.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -173,23 +173,21 @@ const main = async (options: BalancesOptions) => {
};

export const balancesCommand = new Command("balances")
.summary("Fetch native and ZETA token balances")
.option("--evm <address>", "Fetch balances for a specific EVM address")
.option("--solana <address>", "Fetch balances for a specific Solana address")
.option(
"--bitcoin <address>",
"Fetch balances for a specific Bitcoin address"
)
.option("--sui <address>", "Fetch balances for a specific Sui address")
.option("--ton <address>", "Fetch balances for a specific TON address")
.summary("Fetch native and ZRC-20 token balances")
.description("Retrieve token balances on all connected chains")
.option("--evm <address>", "Address on EVM chains")
.option("--solana <address>", "Address on Solana")
.option("--bitcoin <address>", "Address on Bitcoin")
.option("--sui <address>", "Address on Sui")
.option("--ton <address>", "Address on TON")
.option("--name <name>", "Account name")
.addOption(
new Option("--network <network>", "Network to use")
.choices(["mainnet", "testnet"])
.default("testnet")
)
.option("--json", "Output balances as JSON")
.option("--show-zero", "Include zero balances", false)
.option("--show-zero", "Include zero balances in output", false)
.action(async (options: BalancesOptions) => {
const validatedOptions = balancesOptionsSchema.parse(options);
await main(validatedOptions);
Expand Down
5 changes: 4 additions & 1 deletion packages/commands/src/query/cctx.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -249,7 +249,10 @@ const main = async (options: CctxOptions) => {
};

export const cctxCommand = new Command("cctx")
.description("Query cross-chain transaction data in real-time")
.summary("Track the status of a cross-chain transaction.")
.description(
"Queries the real-time status of a cross-chain transaction by its inbound transaction hash. You can control polling frequency, timeout, and target RPC endpoint."
)
.requiredOption("-h, --hash <hash>", "Inbound transaction hash")
Copy link
Contributor

Choose a reason for hiding this comment

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

💡 Verification agent

🧩 Analysis chain

Potential conflict: short flag “-h” is commonly reserved for help in Commander.

Commander defaults the help option to “-h, --help”. Reusing “-h” for “--hash” can shadow/override help or cause conflicts depending on version/config. Suggest changing the short flag (e.g., “-i, --hash” or drop the short flag) in a follow-up PR to avoid a breaking CLI change here.

Run this repo-scope check to find any other places where “-h” is used for non-help and whether help flags are customized:

🏁 Script executed:

#!/usr/bin/env bash
# Find custom options using -h short flag
rg -nP --type=ts -C2 'requiredOption\(\s*["'\'']-h[,\s]' 

# Check for help option customizations
rg -nP --type=ts -C2 '\.helpOption\('

Length of output: 608

Avoid using “-h” for hash flag—it conflicts with the default help shortcut

Our repository-wide grep shows that the only occurrence of a custom -h flag is here, and there is no reconfiguration of the built-in help option—Commander will still reserve -h for --help, so the new -h, --hash binding will override or break the help command:

• packages/commands/src/query/cctx.ts:256
.requiredOption("-h, --hash <hash>", "Inbound transaction hash")

This is a breaking CLI change. Please update the short flag for the hash parameter (for example, -x, --hash or drop the short form) in a follow-up PR.

🤖 Prompt for AI Agents 
In packages/commands/src/query/cctx.ts around line 256, the option currently
uses the short flag `-h` which conflicts with Commander’s built-in help; replace
the short flag with a non-conflicting letter (for example `-x, --hash <hash>`)
or remove the short form entirely so the option becomes `--hash <hash>`, and
update any nearby usage or help text/comments to match the new flag.

.option("-r, --rpc <rpc>", "RPC endpoint", DEFAULT_API_URL)
.option(
Expand Down
5 changes: 4 additions & 1 deletion packages/commands/src/query/chains/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,10 @@ import { showCommand } from "./show";

export const chainsCommand = new Command("chains")
.alias("c")
.description("Supported chains commands")
.summary("View connected chain information")
.description(
"Provides commands to list all chains connected to ZetaChain or view details about a specific chain by name or chain ID."
)
.addCommand(listCommand)
.addCommand(showCommand)
.helpCommand(false);
5 changes: 3 additions & 2 deletions packages/commands/src/query/chains/list.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -138,11 +138,12 @@ from that connected chain to be observed`);

export const listCommand = new Command("list")
.alias("l")
.description("List all supported chains")
.summary("List all connected chains")
.description("Retrieve a list of all supported chains connected to ZetaChain")
.addOption(
new Option("--api <url>", "API endpoint URL").default(DEFAULT_API_URL)
)
.option("--json", "Output chains as JSON")
.option("--json", "Output in JSON format")
.action(async (options: ChainsListOptions) => {
const validatedOptions = chainsListOptionsSchema.parse(options);
await main(validatedOptions);
Expand Down
10 changes: 4 additions & 6 deletions packages/commands/src/query/chains/show.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -332,8 +332,9 @@ const main = async (options: ChainsShowOptions) => {

export const showCommand = new Command("show")
.alias("s")
.summary("Show details for a connected chain")
.description(
"Show detailed information for a specific chain (by chain name or chain ID)"
"Fetches detailed information about a connected chain by name or chain ID. You can query both testnet and mainnet endpoints, and optionally return only a specific field for scripting."
)
.addOption(
new Option("--api-testnet <url>", "Testnet API endpoint URL").default(
Expand All @@ -352,12 +353,9 @@ export const showCommand = new Command("show")
new Option("-c, --chain-id <chain-id>", "Chain ID").conflicts(["chain"])
)
.addOption(
new Option(
"--field -f <field>",
"Return specific field value (for scripting)"
)
new Option("--field -f <field>", "Return only a specific field value")
)
.option("--json", "Output chain as JSON")
.option("--json", "Output in JSON format")
.action(async (options: ChainsShowOptions) => {
const validatedOptions = chainsShowOptionsSchema.parse(options);
await main(validatedOptions);
Expand Down
10 changes: 7 additions & 3 deletions packages/commands/src/query/fees.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -77,17 +77,21 @@ const main = async (params: FeesParams, options: FeesCLIOptions) => {
};

export const feesCommand = new Command("fees")
.description("Fetch omnichain and cross-chain messaging fees")
.summary("Get cross-chain fees")
.description("Estimate fees for cross-chain transactions")
.addOption(
new Option("--api <url>", "API endpoint URL").default(DEFAULT_API_URL)
)
.addOption(
new Option("--rpc <url>", "RPC endpoint URL").default(DEFAULT_EVM_RPC_URL)
)
.addOption(
new Option("--gas-limit <limit>", "Gas limit for withdraw and call")
new Option(
"--gas-limit <limit>",
"Gas limit for withdraw and call transactions"
)
)
.addOption(new Option("--json", "Output results in JSON format"))
.addOption(new Option("--json", "Output in JSON format"))
.action(async (options) => {
const params = feesParamsSchema.parse(options);
const validatedOptions = feesCLIOptionsSchema.parse(options);
Expand Down
7 changes: 6 additions & 1 deletion packages/commands/src/query/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,7 +8,12 @@ import { tokensCommand } from "./tokens";

export const queryCommand = new Command("query")
.alias("q")
.summary("Query commands")
.summary("Query ZetaChain data and connected chain information")
.description(
`Provides a set of tools to fetch on-chain data from ZetaChain and its connected chains.

You can retrieve balances, token information, supported chain details, cross-chain transaction status, and fee estimates for cross-chain operations.`
)
.addCommand(balancesCommand)
.addCommand(cctxCommand)
.addCommand(feesCommand)
Expand Down
5 changes: 4 additions & 1 deletion packages/commands/src/query/tokens/index.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,7 +5,10 @@ import { showCommand } from "./show";

export const tokensCommand = new Command("tokens")
.alias("t")
.description("ZRC-20 token commands")
.summary("Work with tokens on ZetaChain")
.description(
"Provides commands to list all available ZRC-20 tokens or view detailed information about a specific token. Useful for discovering token metadata, contract addresses, and supported chains."
)
.addCommand(listCommand)
.addCommand(showCommand)
.helpCommand(false);
7 changes: 4 additions & 3 deletions packages/commands/src/query/tokens/list.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -94,13 +94,14 @@ const main = async (options: TokensListOptions) => {

export const listCommand = new Command("list")
.alias("l")
.description("List all ZRC-20 tokens")
.summary("List all ZRC-20 tokens")
.description("Fetch and display all registered ZRC-20 tokens on ZetaChain")
.addOption(
new Option("--api <url>", "API endpoint URL").default(DEFAULT_API_URL)
)
.option("--json", "Output tokens as JSON")
.option("--json", "Output in JSON format")
.addOption(
new Option("--columns <values...>", "Additional columns to show")
new Option("--columns <values...>", "Additional columns to display")
.choices(["asset", "type", "decimals"])
.default([])
)
Expand Down
9 changes: 6 additions & 3 deletions packages/commands/src/query/tokens/show.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -143,7 +143,10 @@ const main = async (options: TokensShowOptions) => {

export const showCommand = new Command("show")
.alias("s")
.description("Show detailed information for a specific ZRC-20 token")
.summary("Show details for a ZRC-20 token")
.description(
"Display detailed information about a specific ZRC-20 token by symbol; supports returning a single field for scripting"
)
.addOption(
new Option("--api <url>", "API endpoint URL").default(DEFAULT_API_URL)
)
Expand All @@ -156,10 +159,10 @@ export const showCommand = new Command("show")
.addOption(
new Option(
"--field -f <field>",
"Return specific field value (for scripting). Use 'zrc20' as shorthand for 'zrc20_contract_address'"
"Return only a specific field value. Use 'zrc20' as shorthand for 'zrc20_contract_address'"
)
)
.option("--json", "Output token as JSON")
.option("--json", "Output in JSON format")
.action(async (options: TokensShowOptions) => {
const validatedOptions = tokensShowOptionsSchema.parse(options);
await main(validatedOptions);
Expand Down
3 changes: 2 additions & 1 deletion packages/commands/src/solana/call.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,7 +62,8 @@ const main = async (options: CallOptions) => {
};

export const callCommand = createSolanaCommandWithCommonOptions("call")
.description("Call a universal contract on ZetaChain")
.summary("Call a contract on ZetaChain from Solana")
.description("Call a universal contract on ZetaChain from Solana")
.requiredOption(
"--types <types...>",
"List of parameter types (e.g. uint256 address)"
Expand Down
1 change: 1 addition & 0 deletions packages/commands/src/solana/depositAndCall.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,6 +69,7 @@ const main = async (options: DepositAndCallOptions) => {
export const depositAndCallCommand = createSolanaCommandWithCommonOptions(
"deposit-and-call"
)
.summary("Deposit tokens from Solana and call a contract on ZetaChain")
.description(
"Deposit tokens from Solana and call a universal contract on ZetaChain"
)
Expand Down
Loading