Skip to content

Commit 179ab19

Browse files
peterarguepeterargue
authored
Merge pull request #2296 from onflow/peter/add-claude-support
Add flow-cli skill and CLAUDE.md
2 parents 8d89e02 + 225d6c2 commit 179ab19

3 files changed

Lines changed: 722 additions & 0 deletions

File tree

‎CLAUDE.md‎

Lines changed: 90 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,90 @@
1+
# CLAUDE.md
2+
3+
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
4+
5+
## Build & Run
6+
7+
```bash
8+
# Build the binary (requires CGO for BLS crypto)
9+
CGO_ENABLED=1 CGO_CFLAGS="-O2 -D__BLST_PORTABLE__ -std=gnu11" GO111MODULE=on go build -o ./cmd/flow/flow ./cmd/flow
10+
11+
# Or use Make
12+
make binary
13+
14+
# Run directly without building
15+
go run cmd/flow/main.go [command]
16+
```
17+
18+
## Testing
19+
20+
```bash
21+
# Run all tests
22+
make test
23+
# Equivalent: CGO_ENABLED=1 CGO_CFLAGS="-O2 -D__BLST_PORTABLE__ -std=gnu11" GO111MODULE=on go test -coverprofile=coverage.txt ./...
24+
25+
# Run a single test package
26+
CGO_ENABLED=1 CGO_CFLAGS="-O2 -D__BLST_PORTABLE__ -std=gnu11" go test ./internal/accounts/...
27+
28+
# Run a specific test
29+
CGO_ENABLED=1 CGO_CFLAGS="-O2 -D__BLST_PORTABLE__ -std=gnu11" go test ./internal/accounts/... -run TestFunctionName
30+
31+
# Skip network-dependent tests (e.g. in sandboxed environments)
32+
SKIP_NETWORK_TESTS=1 make test
33+
```
34+
35+
## Linting
36+
37+
```bash
38+
make lint # Run golangci-lint
39+
make fix-lint # Auto-fix lint issues
40+
make check-headers # Verify Apache license headers on all Go files
41+
go generate ./... # Regenerate generated code (required before lint)
42+
```
43+
44+
## Architecture
45+
46+
The CLI is a [Cobra](https://github.com/spf13/cobra)-based application with three main layers:
47+
48+
### Entry Point
49+
`cmd/flow/main.go` — wires all subcommands into the root `flow` command.
50+
51+
### Command Framework (`internal/command/`)
52+
The `command.Command` struct wraps a `cobra.Command` with two execution modes:
53+
- `Run` — for commands that don't need a loaded `flow.json` state
54+
- `RunS` — for commands that require an initialized project state (`*flowkit.State`)
55+
56+
`Command.AddToParent()` handles all shared boilerplate: loading `flow.json`, resolving network/host, creating the gRPC gateway, initializing `flowkit.Services`, version checking, analytics, and error formatting. **All new commands should use this pattern.**
57+
58+
Every command's run function returns a `command.Result` interface with three output methods: `String()` (human-readable), `Oneliner()` (grep-friendly inline), and `JSON()` (structured). The framework handles `--output`, `--filter`, and `--save` flags automatically.
59+
60+
### Command Packages (`internal/`)
61+
Each feature area is its own package with a top-level `Cmd *cobra.Command` that aggregates subcommands. Pattern:
62+
- `accounts.Cmd` (`internal/accounts/`) — registered in `main.go` via `cmd.AddCommand(accounts.Cmd)`
63+
- Subcommands (e.g., `get.go`, `create.go`) define a package-level `var getCommand = &command.Command{...}` and register via `init()` or the parent's `init()`
64+
65+
Key packages:
66+
- `internal/super/` — high-level "super commands": `flow init`, `flow dev`, `flow generate`, `flow flix`
67+
- `internal/super/generator/` — code generation engine for Cadence contracts, scripts, transactions, and tests
68+
- `internal/dependencymanager/` — `flow deps` commands for managing on-chain contract dependencies
69+
- `internal/config/` — `flow config` subcommands for managing `flow.json`
70+
- `internal/emulator/` — wraps the Flow emulator
71+
72+
### flowkit Dependency
73+
The CLI delegates all blockchain interactions to the `github.com/onflow/flowkit/v2` module (external). The `flowkit.Services` interface is the primary abstraction for network calls. The local `flowkit/` directory is a historical artifact (migrated to the external module) and contains only a README and schema.
74+
75+
### Global Flags
76+
Defined in `internal/command/global_flags.go`, applied to every command: `--network`, `--host`, `--log`, `--output`, `--filter`, `--save`, `--config-path`, `--yes`, `--skip-version-check`.
77+
78+
### Configuration
79+
`flow.json` is the project config file. `flowkit.Load()` reads it. The `internal/config/` commands modify it. `state.Networks()`, `state.Accounts()`, etc. provide typed access.
80+
81+
## CLI Design Conventions
82+
- Commands follow `noun verb` pattern (`flow accounts get`)
83+
- Prefer flags over positional args; use args only for the primary required value
84+
- `--output json` must always work for machine-readable output
85+
- Errors go to stderr; normal output to stdout
86+
- Progress indicators for long-running operations via `logger.StartProgress()` / `logger.StopProgress()`
87+
- Long-running commands support `--yes` to skip confirmation prompts
88+
89+
## License Headers
90+
All Go source files must have the Apache 2.0 license header. Run `make check-headers` to verify.

‎skills/query-blockchain/SKILL.md‎

Lines changed: 291 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,291 @@
1+
---
2+
name: query-blockchain
3+
description: Use when you need to read any data from the Flow blockchain — account state, blocks, events, transaction results, collections, or custom contract state via Cadence scripts.
4+
---
5+
6+
# Querying the Flow Blockchain with flow-cli
7+
8+
## Overview
9+
10+
Use this skill any time you need on-chain data. Choose the right command from the decision table, then run it.
11+
12+
**When the entity commands don't expose what you need, use `flow scripts execute`** — Cadence scripts can query any on-chain state and are the primary tool for anything not covered by the commands below. See [Cadence Scripts](#cadence-scripts).
13+
14+
## Network
15+
16+
Default: **mainnet**. Infer from conversation context:
17+
18+
| Context | Flag |
19+
|---|---|
20+
| Default / production | `--network mainnet` |
21+
| Testnet discussion | `--network testnet` |
22+
| Local development / emulator | `--network emulator` |
23+
24+
Access node endpoints (built-in):
25+
- Mainnet: `access.mainnet.nodes.onflow.org:9000`
26+
- Testnet: `access.devnet.nodes.onflow.org:9000`
27+
- Emulator: `127.0.0.1:3569`
28+
29+
Override with `--host <endpoint>` to point at a custom access node.
30+
31+
## Decision Table
32+
33+
| What you need | Command |
34+
|---|---|
35+
| Account balance, keys, deployed contracts | `flow accounts get` |
36+
| Account staking info | `flow accounts staking-info` |
37+
| Block info | `flow blocks get` |
38+
| Events emitted in a block range | `flow events get` |
39+
| Regular transaction status / result | `flow transactions get` |
40+
| System transaction for a block | `flow transactions get-system` |
41+
| Scheduled transaction details | `flow schedule get` / `flow schedule list` |
42+
| Collection contents | `flow collections get` |
43+
| Network status (online/offline) | `flow status` |
44+
| Protocol state snapshot | `flow snapshot save` |
45+
| Anything not covered above | `flow scripts execute` |
46+
47+
---
48+
49+
## Commands
50+
51+
### Accounts
52+
53+
```bash
54+
flow accounts get <address|name> [--include contracts] [--network mainnet]
55+
```
56+
57+
- `--include contracts` adds deployed contract source code to the output
58+
- Flow addresses must include the `0x` prefix (e.g. `0xf8d6e0586b0a20c7`)
59+
- `<name>` resolves via `flow.json` — only use names when a `flow.json` is present
60+
61+
```bash
62+
flow accounts get 0xe467b9dd11fa00df --network mainnet
63+
flow accounts get 0xe467b9dd11fa00df --include contracts --network mainnet
64+
flow accounts staking-info 0xe467b9dd11fa00df --network mainnet
65+
```
66+
67+
### Blocks
68+
69+
```bash
70+
flow blocks get <block_id|latest|block_height> [--include transactions] [--events <event_name>] [--network mainnet]
71+
```
72+
73+
```bash
74+
flow blocks get latest --network mainnet
75+
flow blocks get 12884163 --include transactions --network mainnet
76+
flow blocks get latest --events A.1654653399040a61.FlowToken.TokensDeposited --network mainnet
77+
```
78+
79+
### Events
80+
81+
```bash
82+
flow events get <event_name> [<event_name2> ...] [--last 10] [--start N --end M] [--network mainnet]
83+
```
84+
85+
- Default: last 10 blocks. Use `--last N` to widen.
86+
- `--start`/`--end` for explicit block height range.
87+
- Multiple event types are fetched in parallel.
88+
- Event name format: `A.<address>.<ContractName>.<EventName>`
89+
90+
```bash
91+
flow events get A.1654653399040a61.FlowToken.TokensDeposited --last 20 --network mainnet
92+
flow events get A.1654653399040a61.FlowToken.TokensDeposited --start 11559500 --end 11559600 --network mainnet
93+
flow events get A.1654653399040a61.FlowToken.TokensDeposited A.1654653399040a61.FlowToken.TokensWithdrawn --network mainnet
94+
```
95+
96+
### Transactions
97+
98+
```bash
99+
# Regular transaction
100+
flow transactions get <tx_id> [--include signatures,code,payload,fee-events] [--exclude events] [--network mainnet]
101+
102+
# System transaction (by block, not tx hash)
103+
flow transactions get-system <block_id|latest|block_height> [tx_id] [--network mainnet]
104+
105+
# Scheduled transactions
106+
flow schedule get <numeric-id> [--network mainnet]
107+
flow schedule list <address|account-name> [--network mainnet]
108+
```
109+
110+
### Collections
111+
112+
```bash
113+
flow collections get <collection_id> [--network mainnet]
114+
```
115+
116+
### Network Status
117+
118+
```bash
119+
flow status --network mainnet
120+
```
121+
122+
---
123+
124+
## Output Format
125+
126+
All commands support `--output json` for machine-readable output.
127+
128+
```bash
129+
flow accounts get 0xe467b9dd11fa00df --output json --network mainnet
130+
flow events get A.1654653399040a61.FlowToken.TokensDeposited --output json --network mainnet
131+
```
132+
133+
Use `--filter <property>` to extract specific fields from results.
134+
135+
---
136+
137+
## Cadence Scripts
138+
139+
`flow scripts execute` is the most powerful read tool. Use it when:
140+
141+
- You need data from a contract that has no dedicated CLI command
142+
- You need to call a `view` function or read a field from a contract
143+
- You need to combine data from multiple contracts in one query
144+
- You need a historical snapshot at a specific block height
145+
146+
```bash
147+
flow scripts execute <script.cdc> [args...] [--args-json '[{"type":"...","value":"..."}]'] [--block-height N] [--block-id <id>] [--network mainnet]
148+
```
149+
150+
- Simple types (Address, UInt64, String, Bool) can be passed as positional args
151+
- Use `--args-json` for complex types (UFix64, optionals, structs, arrays)
152+
- `--block-height` / `--block-id` execute against historical state
153+
- Write a temporary `.cdc` file, execute it, then clean up
154+
155+
### Writing and Running Scripts
156+
157+
Write script to a temp file, execute, clean up:
158+
159+
```bash
160+
# Write
161+
cat > /tmp/query.cdc << 'EOF'
162+
import FungibleToken from 0xf233dcee88fe0abe
163+
import FlowToken from 0x1654653399040a61
164+
165+
access(all) fun main(address: Address): UFix64 {
166+
let account = getAccount(address)
167+
let vaultRef = account.capabilities
168+
.borrow<&{FungibleToken.Balance}>(/public/flowTokenBalance)
169+
?? panic("Could not borrow FungibleToken Balance capability for account \(address) at path /public/flowTokenBalance. Make sure the account has a FlowToken Vault set up properly.")
170+
return vaultRef.balance
171+
}
172+
EOF
173+
174+
# Execute
175+
flow scripts execute /tmp/query.cdc 0xe467b9dd11fa00df --network mainnet
176+
177+
# Clean up
178+
rm /tmp/query.cdc
179+
```
180+
181+
### Passing Arguments
182+
183+
```bash
184+
# Simple types as positional args
185+
flow scripts execute /tmp/query.cdc 0xe467b9dd11fa00df --network mainnet
186+
187+
# Complex types with --args-json (JSON-Cadence encoding)
188+
flow scripts execute /tmp/query.cdc --args-json '[{"type":"UFix64","value":"100.0"},{"type":"Address","value":"0xe467b9dd11fa00df"}]' --network mainnet
189+
190+
# Historical state
191+
flow scripts execute /tmp/query.cdc 0xe467b9dd11fa00df --block-height 12884163 --network mainnet
192+
```
193+
194+
---
195+
196+
## Contract Addresses
197+
198+
| Contract | Mainnet | Testnet | Emulator |
199+
|---|---|---|---|
200+
| FungibleToken | `0xf233dcee88fe0abe` | `0x9a0766d93b6608b7` | `0xee82856bf20e2aa6` |
201+
| FungibleTokenMetadataViews | `0xf233dcee88fe0abe` | `0x9a0766d93b6608b7` | `0xf8d6e0586b0a20c7` |
202+
| FungibleTokenSwitchboard | `0xf233dcee88fe0abe` | `0x9a0766d93b6608b7` | `0xf8d6e0586b0a20c7` |
203+
| Burner | `0xf233dcee88fe0abe` | `0x9a0766d93b6608b7` | `0xf8d6e0586b0a20c7` |
204+
| FlowToken | `0x1654653399040a61` | `0x7e60df042a9c0868` | `0x0ae53cb6e3f42a79` |
205+
| NonFungibleToken | `0x1d7e57aa55817448` | `0x631e88ae7f1d7c20` | `0xf8d6e0586b0a20c7` |
206+
| MetadataViews | `0x1d7e57aa55817448` | `0x631e88ae7f1d7c20` | `0xf8d6e0586b0a20c7` |
207+
| ViewResolver | `0x1d7e57aa55817448` | `0x631e88ae7f1d7c20` | `0xf8d6e0586b0a20c7` |
208+
| FlowFees | `0xf919ee77447b7497` | `0x912d5440f7e3769e` | `0xe5a8b7f23e8b548f` |
209+
| FlowServiceAccount | `0xe467b9dd11fa00df` | `0x8c5303eaa26202d6` | `0xf8d6e0586b0a20c7` |
210+
| FlowStorageFees | `0xe467b9dd11fa00df` | `0x8c5303eaa26202d6` | `0xf8d6e0586b0a20c7` |
211+
| NodeVersionBeacon | `0xe467b9dd11fa00df` | `0x8c5303eaa26202d6` | `0xf8d6e0586b0a20c7` |
212+
| RandomBeaconHistory | `0xe467b9dd11fa00df` | `0x8c5303eaa26202d6` | `0xf8d6e0586b0a20c7` |
213+
| FlowIDTableStaking | `0x8624b52f9ddcd04a` | `0x9eca2b38b18b5dfe` | `0xf8d6e0586b0a20c7` |
214+
| FlowEpoch | `0x8624b52f9ddcd04a` | `0x9eca2b38b18b5dfe` | `0xf8d6e0586b0a20c7` |
215+
| FlowClusterQC | `0x8624b52f9ddcd04a` | `0x9eca2b38b18b5dfe` | `0xf8d6e0586b0a20c7` |
216+
| FlowDKG | `0x8624b52f9ddcd04a` | `0x9eca2b38b18b5dfe` | `0xf8d6e0586b0a20c7` |
217+
| FlowStakingCollection | `0x8d0e87b65159ae63` | `0x95e019a17d0e23d7` | `0xf8d6e0586b0a20c7` |
218+
| LockedTokens | `0x8d0e87b65159ae63` | `0x95e019a17d0e23d7` | `0xf8d6e0586b0a20c7` |
219+
| StakingProxy | `0x62430cf28c26d095` | `0x7aad92e5a0715d21` | `0xf8d6e0586b0a20c7` |
220+
| EVM | `0xe467b9dd11fa00df` | `0x8c5303eaa26202d6` | `0xf8d6e0586b0a20c7` |
221+
| FlowEVMBridge ¹ | `0x1e4aa0b87d10b141` | `0xdfc20aee650fcbdf` | `0xf8d6e0586b0a20c7` |
222+
| NFTStorefrontV2 | `0x1d7e57aa55817448` | `0x2d55b98eb200daef` | `0xf8d6e0586b0a20c7` |
223+
| HybridCustody | `0xd8a7e05a7ac670c0` | `0x294e44e1ec6993c6` | `0xf8d6e0586b0a20c7` |
224+
| CapabilityFactory | `0xd8a7e05a7ac670c0` | `0x294e44e1ec6993c6` | `0xf8d6e0586b0a20c7` |
225+
| CapabilityFilter | `0xd8a7e05a7ac670c0` | `0x294e44e1ec6993c6` | `0xf8d6e0586b0a20c7` |
226+
| CapabilityDelegator | `0xd8a7e05a7ac670c0` | `0x294e44e1ec6993c6` | `0xf8d6e0586b0a20c7` |
227+
228+
¹ The EVM bridge account hosts many contracts beyond FlowEVMBridge itself (FlowEVMBridgeConfig, FlowEVMBridgeUtils, FlowEVMBridgeNFTEscrow, FlowEVMBridgeTokenEscrow, CrossVMNFT, CrossVMToken, and more). Run `flow accounts get 0x1e4aa0b87d10b141 --network mainnet` for the current deployed contract list, or check the [flow-evm-bridge](https://github.com/onflow/flow-evm-bridge) repo for available scripts.
229+
230+
---
231+
232+
## Cadence Script Recipes & Data Structures
233+
234+
See [cadence-scripts.md](cadence-scripts.md) for 20+ ready-to-use Cadence scripts organized by category:
235+
- **Token queries** — FLOW balance, total supply, generic FT balance, FT metadata
236+
- **Account & storage** — storage capacity, available balance, account creation fee, fee parameters
237+
- **Epoch** — counter, phase, metadata, timing config
238+
- **Staking** — node info, staked node IDs, total staked, by role, requirements, rewards, delegator info, staking collections
239+
- **Protocol** — node version beacon, random beacon source
240+
- **NFT** — collection IDs, NFT metadata (Display)
241+
- **Key data structures** — NodeInfo, DelegatorInfo, EpochMetadata, EpochPhase, Node Roles
242+
243+
---
244+
245+
## Common Event Types
246+
247+
| Event | Description |
248+
|---|---|
249+
| `A.f233dcee88fe0abe.FungibleToken.Deposited` | Any fungible token deposited |
250+
| `A.f233dcee88fe0abe.FungibleToken.Withdrawn` | Any fungible token withdrawn |
251+
| `A.f233dcee88fe0abe.FungibleToken.Burned` | Any fungible token burned |
252+
| `A.1d7e57aa55817448.NonFungibleToken.Deposited` | Any NFT deposited to a collection |
253+
| `A.1d7e57aa55817448.NonFungibleToken.Withdrawn` | Any NFT withdrawn from a collection |
254+
| `A.8624b52f9ddcd04a.FlowEpoch.NewEpoch` | New epoch started |
255+
| `A.8624b52f9ddcd04a.FlowEpoch.EpochSetup` | Epoch setup phase began |
256+
| `A.8624b52f9ddcd04a.FlowEpoch.EpochCommit` | Epoch commit phase began |
257+
| `A.8624b52f9ddcd04a.FlowIDTableStaking.NewNodeCreated` | New staking node registered |
258+
| `A.8624b52f9ddcd04a.FlowIDTableStaking.TokensCommitted` | Tokens committed to stake |
259+
| `A.8624b52f9ddcd04a.FlowIDTableStaking.RewardsPaid` | Staking rewards distributed |
260+
| `A.8624b52f9ddcd04a.FlowIDTableStaking.NewDelegatorCreated` | New delegator registered |
261+
| `A.f919ee77447b7497.FlowFees.FeesDeducted` | Transaction fees paid |
262+
| `A.f919ee77447b7497.FlowFees.TokensDeposited` | Fees deposited to fee vault |
263+
264+
---
265+
266+
## Available Script Libraries
267+
268+
For more complex queries, clone these repos to `/tmp` and use their scripts directly:
269+
270+
| Repo | Scripts Path | Use For |
271+
|---|---|---|
272+
| [flow-core-contracts](https://github.com/onflow/flow-core-contracts) | `transactions/*/scripts/` | Staking, epoch, fees, locked tokens, version beacon, random beacon |
273+
| [flow-ft](https://github.com/onflow/flow-ft) | `transactions/scripts/`, `transactions/metadata/scripts/` | FT balances, supply, metadata, switchboard |
274+
| [flow-nft](https://github.com/onflow/flow-nft) | `transactions/scripts/` | NFT collections, metadata views, cross-VM views |
275+
| [flow-evm-bridge](https://github.com/onflow/flow-evm-bridge) | `cadence/scripts/` | Bridge state, onboarding checks, escrow, EVM balances, cross-VM associations |
276+
| [nft-storefront](https://github.com/onflow/nft-storefront) | `scripts/` | Marketplace listings, ghost listings, commission receivers, storefront IDs |
277+
| [hybrid-custody](https://github.com/onflow/hybrid-custody) | `scripts/hybrid-custody/`, `scripts/delegator/`, `scripts/factory/` | Child/parent account relationships, cross-account NFT/FT access, capability delegation |
278+
279+
```bash
280+
# Example: use an existing script from flow-core-contracts
281+
git clone --depth 1 https://github.com/onflow/flow-core-contracts.git /tmp/flow-core-contracts
282+
flow scripts execute /tmp/flow-core-contracts/transactions/idTableStaking/scripts/get_node_info.cdc "abc123...def456" --network mainnet
283+
```
284+
285+
Note: Some repo scripts use `import "ContractName"` syntax (no address). These require a `flow.json` with address mappings. For ad-hoc queries, replace with explicit addresses:
286+
```cadence
287+
// Repo style (requires flow.json aliases):
288+
import "FlowToken"
289+
// Direct style (works without flow.json):
290+
import FlowToken from 0x1654653399040a61
291+
```

0 commit comments

Comments
 (0)