diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 000000000..52ca32a89 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,106 @@ +# AGENTS.md + +Guidance for AI coding agents working in this repo. Every claim below is sourced from the +Makefile, `go.mod`, `ci.yml`, `CONTRIBUTING.md`, or verified source files — do not add +unverified commands or paths. + +## Overview + +`flow-cli` is the official command-line tool for the Flow blockchain: deploy contracts, run +transactions/scripts, manage accounts/keys, and run a bundled emulator. Go 1.25.1 module +(`github.com/onflow/flow-cli`), built on [Cobra](https://github.com/spf13/cobra). All +blockchain logic is delegated to the external `github.com/onflow/flowkit/v2` module. Entry +point is `cmd/flow/main.go`. License: Apache-2.0. + +## Build and Test Commands + +CGO is required (BLS crypto). `go build` / `go test` need these env vars set: +`CGO_ENABLED=1 CGO_CFLAGS="-O2 -D__BLST_PORTABLE__ -std=gnu11"`. + +- `make binary` — build `./cmd/flow/flow`; ldflags inject version, commit, and analytics tokens +- `make test` — `go test -coverprofile=coverage.txt ./...` with CGO flags set +- `make ci` — `generate test coverage` (this is what GitHub Actions runs) +- `make coverage` — emits `index.html` and `cover-summary.txt`, only when `COVER=true` +- `make lint` — `golangci-lint run -v ./...`; depends on `make generate` +- `make fix-lint` — golangci-lint with `--fix` +- `make generate` — `go generate ./...`; run before `lint`, `ci`, or any test touching generated code +- `make check-headers` — `./check-headers.sh`, verifies Apache-2.0 header on every `.go` file +- `make check-tidy` — `go mod tidy` (CI runs this; fails if `go.mod`/`go.sum` drift) +- `make clean` — removes binaries under `cmd/flow/` +- `make versioned-binaries` — cross-compiles linux/darwin/windows × amd64/arm64 +- `make publish` — uploads versioned binaries to `gs://flow-cli` via `gsutil` +- `make release` — runs `ghcr.io/goreleaser/goreleaser-cross:v1.25.0` in Docker +- `make test-e2e-emulator` — `flow -f tests/flow.json emulator start` +- `SKIP_NETWORK_TESTS=1 make test` — skip tests that reach Flow mainnet/testnet (CONTRIBUTING.md) +- `nix develop` — enter dev shell from `flake.nix`; then `go run cmd/flow/main.go` + +## Architecture + +Cobra CLI. `cmd/flow/main.go` wires every subcommand into the root `flow` command and defines +eight command groups (super, resources, interactions, tools, project, security, manager, schedule). + +**`internal/command/`** — shared framework. `command.Command` wraps `cobra.Command` with two +run modes: `Run` (no project state) and `RunS` (requires `*flowkit.State` loaded from +`flow.json`). `AddToParent()` handles loading `flow.json`, gateway/network resolution, +`flowkit.Services` init, version check, analytics, and error formatting. Global flags +(`internal/command/global_flags.go`): `--network`, `--host`, `--log`, `--output`, `--filter`, +`--save`, `--config-path`, `--yes`, `--skip-version-check`. Every `Result` must implement +`String()`, `Oneliner()`, and `JSON()`. + +**`internal/super/`** — super commands (`flow init`, `flow dev`, `flow generate`, `flow flix`). +Scaffolding engine under `internal/super/generator/` with `templates/` and `fixtures/`. + +**Feature packages** (`internal//`) — one per top-level command; each exports a +`Cmd *cobra.Command` (or `Command`) registered in `main.go`: +`accounts`, `blocks`, `cadence`, `collections`, `config`, `dependencymanager`, `emulator`, +`events`, `evm`, `keys`, `mcp`, `project`, `quick` (`flow deploy`, `flow run`), `schedule` +(transaction scheduler: `setup`/`get`/`list`/`cancel`/`parse`), `scripts`, `settings`, +`signatures`, `snapshot`, `status`, `test`, `tools` (`dev-wallet`, `flowser`), `transactions`, +`version`. Support: `internal/util/`, `internal/prompt/`. + +**`build/build.go`** — version/commit variables injected via `-ldflags` at build time. +**`common/branding/`** — styling/ASCII constants. +**`flowkit/`** (top-level) — **historical artifact**; contains only `README.md` and +`schema.json`. All Go code moved to the external `github.com/onflow/flowkit/v2`. +**`docs/`** — hand-maintained Markdown reference pages, one per command, published to +developers.flow.com. +**`testing/better/`** — shared test helpers. + +## Conventions and Gotchas + +- **`make generate` before `make lint` and CI workflows.** `lint` declares `generate` as a + prerequisite; `ci` runs `generate test coverage` in that order. +- **CGO is not optional.** Plain `go build ./...` / `go test ./...` without the CGO env vars + above will fail on the BLS crypto dependency (`__BLST_PORTABLE__`). +- **Register new commands via `command.Command.AddToParent(cmd)`** (not raw `cmd.AddCommand`) + so shared boilerplate — `flow.json` load, gateway init, error formatting — runs. See + `cmd/flow/main.go` for both registration styles. +- **Command naming is `noun verb`** (`flow accounts get`, not `flow get-accounts`) — see + "CLI Guidelines" in `CONTRIBUTING.md`. +- **Prefer flags over positional args.** Use an arg only for the single primary required value. +- **`--output json` must always work.** Every `Result` implements `JSON()`; never gate + machine-readable output behind a subcommand. +- **stdout for normal output, stderr for errors.** No stack traces on error; `--log debug` + is the escape hatch. +- **Every `.go` file needs the Apache-2.0 header.** `check-headers.sh` greps for + `Licensed under the Apache License` or `Code generated (from|by)` and fails CI otherwise. +- **goimports `local-prefixes: github.com/onflow/flow-cli`** (`.golangci.yml`) — internal + imports group separately from third-party. +- **Linters enabled:** `errcheck`, `govet`, `ineffassign`, `misspell`, plus `goimports` + formatter. CI pins `golangci-lint v2.4.0` (`.github/workflows/ci.yml`). +- **`SKIP_NETWORK_TESTS=1`** skips tests that reach mainnet/testnet nodes — use in Nix or + egress-restricted CI (CONTRIBUTING.md "Skipping Network-Dependent Tests"). +- **`syscall.Exit` in `cmd/flow/main.go` is intentional** — works around a gRPC cleanup + regression that appeared in Go 1.23.1 (inline comment in `main.go`). +- **`version.txt` is deprecated** for CLI versions after v1.18.0 (CONTRIBUTING.md + "Releasing"). The semver is derived from the git tag via `-ldflags` into `build.semver`. +- **Analytics tokens (`MIXPANEL_PROJECT_TOKEN`, `ACCOUNT_TOKEN`) are baked in at build time** + via ldflags in the Makefile — rebuild, don't patch the binary. + +## Files Not to Modify + +- `go.sum` — regenerate via `go mod tidy` / `make check-tidy`, never hand-edit. +- `flake.lock` — update via `nix flake update`. +- `flowkit/` top-level directory — legacy stub; real code lives in `github.com/onflow/flowkit/v2`. +- `version.txt` — deprecated post v1.18.0; leave it. +- `cli-banner.svg`, `cli.gif` — release artifacts. diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 000000000..71500c031 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,7 @@ +# Changelog + +Release notes and version history for flow-cli are tracked via GitHub Releases: + +- https://github.com/onflow/flow-cli/releases + +For user-facing changes per version, see the Releases page. diff --git a/CITATION.cff b/CITATION.cff new file mode 100644 index 000000000..a94bfb59f --- /dev/null +++ b/CITATION.cff @@ -0,0 +1,17 @@ +cff-version: 1.2.0 +message: "If you use flow-cli in your research or reference it, please cite it as below." +title: "flow-cli: The Flow Command-Line Interface" +authors: + - name: "Flow Foundation" + website: "https://flow.com" +repository-code: "https://github.com/onflow/flow-cli" +url: "https://flow.com" +license: Apache-2.0 +type: software +keywords: + - flow + - flow-network + - flow-cli + - cadence + - blockchain + - developer-tools diff --git a/README.md b/README.md index 94278973b..50bff2778 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,11 @@ -
+# flow-cli — The Flow Command-Line Interface + +[![License](https://img.shields.io/github/license/onflow/flow-cli)](https://github.com/onflow/flow-cli/blob/master/LICENSE) +[![Release](https://img.shields.io/github/v/release/onflow/flow-cli)](https://github.com/onflow/flow-cli/releases) +[![Discord](https://img.shields.io/discord/613813861610684416?label=Discord&logo=discord)](https://discord.gg/flow) +[![Built on Flow](https://img.shields.io/badge/Built%20on-Flow-00EF8B)](https://flow.com) +[![Go Reference](https://pkg.go.dev/badge/github.com/onflow/flow-cli.svg)](https://pkg.go.dev/github.com/onflow/flow-cli) +

Logo @@ -17,8 +24,16 @@ Read Guidelines

-
-
+ +## TL;DR + +- **What:** Official command-line interface for the Flow network. Deploy contracts, run transactions and scripts, manage accounts and keys, and run a local emulator from your terminal. +- **Who it's for:** Developers building dapps, smart contracts, or tooling on Flow. +- **Why use it:** A single tool covering project scaffolding, local development, contract deployment, and network interaction across emulator, testnet, and mainnet. +- **Status:** see [Releases](https://github.com/onflow/flow-cli/releases) for the latest version. +- **License:** Apache-2.0. +- **Related repos:** [onflow/cadence](https://github.com/onflow/cadence) · [onflow/flow-go](https://github.com/onflow/flow-go) · [onflow/fcl-js](https://github.com/onflow/fcl-js) +- The reference command-line interface for the Flow network, open-sourced since 2019. ## Installation @@ -29,7 +44,7 @@ To install the Flow CLI, follow the [installation instructions](https://develope You can find the CLI documentation on the [CLI documentation website](https://developers.flow.com/tools/flow-cli). ## Features -The Flow CLI is a command line tool that allows you to interact with the Flow blockchain. +The Flow CLI is a command line tool that allows you to interact with the Flow network. Read about supported commands in the [CLI documentation website](https://developers.flow.com/tools/flow-cli). ``` @@ -82,3 +97,35 @@ The Flow CLI includes several commands to interact with Flow networks, such as q ## Contributing Read [contributing](./CONTRIBUTING.md) document. + +## FAQ + +**What is the Flow CLI?** +The Flow CLI is a command-line tool for interacting with the Flow network. It supports deploying contracts, sending transactions, running scripts, managing accounts and keys, and running a local emulator. + +**How do I install the Flow CLI?** +Follow the installation instructions at [developers.flow.com/tools/flow-cli/install](https://developers.flow.com/tools/flow-cli/install). Installers are provided for macOS, Linux, and Windows. + +**How do I start a new Flow project?** +Run `flow init` to scaffold a new project. This uses the super commands described in the Features section above. + +**Does the Flow CLI include a local emulator?** +Yes. The CLI bundles the [Flow Emulator](https://developers.flow.com/tools/emulator) so you can develop and test locally before deploying to testnet or mainnet. + +**Where can I find the reference for `flow.json`?** +See [docs/configuration.md](./docs/configuration.md) in this repo and the [configuration reference](https://developers.flow.com/tools/flow-cli) on the docs site. + +**How do I report a bug or request a feature?** +Open an issue at [github.com/onflow/flow-cli/issues](https://github.com/onflow/flow-cli/issues). For security issues, follow [SECURITY.md](./SECURITY.md). + +**What license is the Flow CLI released under?** +Apache-2.0. See [LICENSE](./LICENSE). + +## About Flow + +This repo is part of the [Flow network](https://flow.com), a Layer 1 blockchain built for consumer applications, AI Agents, and DeFi at scale. + +- Developer docs: https://developers.flow.com +- Cadence language: https://cadence-lang.org +- Community: [Flow Discord](https://discord.gg/flow) · [Flow Forum](https://forum.flow.com) +- Governance: [Flow Improvement Proposals](https://github.com/onflow/flips)