diff --git a/.github/actions/update-with-latest-versions/Dockerfile b/.github/actions/update-with-latest-versions/Dockerfile index 6f0c98049..2afdb64b7 100644 --- a/.github/actions/update-with-latest-versions/Dockerfile +++ b/.github/actions/update-with-latest-versions/Dockerfile @@ -1,4 +1,4 @@ -FROM golang:1.25 +FROM golang:1.26 ENV DEBIAN_FRONTEND=noninteractive RUN apt update && apt install -y jq && rm -rf /var/lib/apt/lists/* diff --git a/docs/reference/kubo/cli.md b/docs/reference/kubo/cli.md index 9826697ec..219bcbb7c 100644 --- a/docs/reference/kubo/cli.md +++ b/docs/reference/kubo/cli.md @@ -5,8 +5,8 @@ description: API documentation for the Kubo command-line executable. # Kubo command-line -::: tip Generated on 2025-12-02 22:04:13, from kubo 0.39.0 -This document was autogenerated from CLI help text in [kubo 0.39.0](https://github.com/ipfs/kubo/releases/tag/v0.39.0) +::: tip Generated on 2026-02-26 02:27:01, from kubo 0.40.0 +This document was autogenerated from CLI help text in [kubo 0.40.0](https://github.com/ipfs/kubo/releases/tag/v0.40.0) For issues and support, check out the [generate-cli-docs.sh](https://github.com/ipfs/ipfs-docs/blob/main/docs/reference/kubo/generate-cli-docs.sh) script on GitHub. ::: @@ -27,13 +27,18 @@ Every command usable from the CLI is also available through the [RPC API v0](rpc /ip4/104.131.131.82/tcp/4001/p2p/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ /ip4/104.236.151.122/tcp/4001/p2p/QmSoLju6m7xTh3DuokvT3886QRYqxAzb1kShaanJgW36yx /ip4/104.236.176.52/tcp/4001/p2p/QmSoLnSGccFuZQJzRadHn95W2CrSFmZuTdDWP8HXaHca9z +``` +CLI with `--enc=json` produces the same JSON as the HTTP RPC API: +``` > curl -X POST http://127.0.0.1:5001/api/v0/swarm/peers { - "Strings": [ - "/ip4/104.131.131.82/tcp/4001/p2p/QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ", - "/ip4/104.236.151.122/tcp/4001/p2p/QmSoLju6m7xTh3DuokvT3886QRYqxAzb1kShaanJgW36yx", - "/ip4/104.236.176.52/tcp/4001/p2p/QmSoLnSGccFuZQJzRadHn95W2CrSFmZuTdDWP8HXaHca9z", + "Peers": [ + { + "Addr": "/ip4/104.131.131.82/tcp/4001", + "Peer": "QmaCpDMGvV2BGHeYERUEnRQAwe3N8SzbUtfsmvsqQLuvuJ", + ... + } ] } ``` @@ -177,11 +182,12 @@ USAGE SYNOPSIS ipfs add [--recursive | -r] [--dereference-args] [--stdin-name=] [--hidden | -H] [--ignore=]... - [--ignore-rules-path=] [--quiet | -q] - [--quieter | -Q] [--silent] [--progress | -p] [--only-hash | -n] - [--wrap-with-directory | -w] [--pin=false] [--pin-name=] - [--to-files=] [--cid-version=] [--hash=] - [--raw-leaves] [--chunker= | -s] [--trickle | -t] + [--ignore-rules-path=] [--empty-dirs=false] + [--dereference-symlinks] [--quiet | -q] [--quieter | -Q] [--silent] + [--progress | -p] [--only-hash | -n] [--wrap-with-directory | -w] + [--pin=false] [--pin-name=] [--to-files=] + [--cid-version=] [--hash=] [--raw-leaves] + [--chunker= | -s] [--trickle | -t] [--max-file-links=] [--max-directory-links=] [--max-hamt-fanout=] [--inline] @@ -197,8 +203,9 @@ ARGUMENTS OPTIONS -r, --recursive bool - Add directory paths recursively. - --dereference-args bool - Symlinks supplied in arguments are - dereferenced. + --dereference-args bool - DEPRECATED: use --dereference-symlinks + instead. Only dereferences symlinks in + CLI arguments, not inside directories. --stdin-name string - Assign a name if the file source is stdin. -H, --hidden bool - Include files that are hidden. Only takes effect on recursive add. @@ -207,6 +214,11 @@ OPTIONS experimental). --ignore-rules-path string - A path to a file with .gitignore-style ignore rules (experimental). + -E, --empty-dirs bool - Include empty directories in the import. + Default: true. + --dereference-symlinks bool - Recursively resolve all symlinks to their + target content. Works on symlinks inside + directories, not just CLI arguments. -q, --quiet bool - Write minimal output. -Q, --quieter bool - Write only final hash. --silent bool - Write no output. @@ -337,6 +349,18 @@ DESCRIPTION See 'ipfs files --help' to learn more about using MFS for keeping track of added files and directories. + SYMLINK HANDLING: + + By default, symbolic links are preserved as UnixFS symlink nodes that store + the target path. Use --dereference-symlinks to resolve symlinks to their + target content instead: + + > ipfs add -r --dereference-symlinks ./mydir + + This resolves all symlinks, including CLI arguments and those found inside + directories. Symlinks to files become regular file content, symlinks to + directories are traversed and their contents are added. + CHUNKING EXAMPLES: The chunker option, '-s', specifies the chunking strategy that dictates @@ -348,6 +372,16 @@ DESCRIPTION specifying buzhash or rabin-[min]-[avg]-[max] (where min/avg/max refer to the desired chunk sizes in bytes), e.g. 'rabin-262144-524288-1048576'. + The maximum accepted value for 'size-N' and rabin 'max' parameter is + 2MiB minus 256 bytes (2096896 bytes). The 256-byte overhead budget is + reserved for protobuf/UnixFS framing so that serialized blocks stay + within the 2MiB block size limit from the bitswap spec. The buzhash + chunker uses a fixed internal maximum of 512KiB and is not affected. + + Only the fixed-size chunker ('size-N') guarantees that the same data + will always produce the same CID. The rabin and buzhash chunkers may + change their internal parameters in a future release. + The following examples use very small byte sizes to demonstrate the properties of the different chunkers on a small file. You'll likely want to use a 1024 times larger chunk sizes for most files. @@ -559,7 +593,7 @@ OPTIONS --mhlen int - Multihash hash length. Default: -1. --pin bool - Pin added blocks recursively. Default: false. --allow-big-block bool - Disable block size check and allow creation of - blocks bigger than 1MiB. WARNING: such blocks + blocks bigger than 2MiB. WARNING: such blocks won't be transferable over the standard bitswap. Default: false. -f, --format string - Use legacy format for returned CID (DEPRECATED). @@ -1178,7 +1212,9 @@ DESCRIPTION Bootstrap peers, DNS resolvers, delegated routers, and IPNS delegated publishers are set to "auto". This profile requires AutoConf to be enabled and configured. 'badgerds': - Configures the node to use the legacy badgerv1 datastore. + DEPRECATED: Configures the node to use the legacy badgerv1 datastore. + This profile will be removed in a future Kubo release. + New deployments should use 'flatfs' or 'pebbleds' instead. NOTE: this is badger 1.x, which has known bugs and is no longer supported by the upstream team. It is provided here only for pre-existing users, allowing them to migrate away to more modern datastore. @@ -1193,6 +1229,14 @@ DESCRIPTION * Good for medium-size datastores, but may run into performance issues if your dataset is bigger than a terabyte. + To migrate: create a new IPFS_PATH with 'ipfs init --profile=flatfs', + move pinned data via 'ipfs dag export/import' or 'ipfs pin ls -t recursive|add', + and decommission the old badger-based node. + When it comes to block storage, use experimental 'pebbleds' only if you are sure + modern 'flatfs' does not serve your use case (most users will be perfectly fine + with flatfs, it is also possible to keep flatfs for blocks and replace leveldb + with pebble if preferred over leveldb). + See configuration documentation at: https://github.com/ipfs/kubo/blob/master/docs/datastores.md#badgerds @@ -1200,8 +1244,9 @@ DESCRIPTION via 'ipfs init --profile badgerds' 'badgerds-measure': - Configures the node to use the legacy badgerv1 datastore with metrics wrapper. - Additional '*_datastore_*' metrics will be exposed on /debug/metrics/prometheus + DEPRECATED: Configures the node to use the legacy badgerv1 datastore with metrics wrapper. + This profile will be removed in a future Kubo release. + New deployments should use 'flatfs' or 'pebbleds' instead. NOTE: This profile may only be applied when first initializing node at IPFS_PATH via 'ipfs init --profile badgerds-measure' @@ -1244,7 +1289,7 @@ DESCRIPTION via 'ipfs init --profile flatfs-measure' 'legacy-cid-v0': - Makes UnixFS import produce legacy CIDv0 with no raw leaves, sha2-256 and 256 KiB chunks. This is likely the least optimal preset, use only if legacy behavior is required. + Alias for unixfs-v0-2015 profile. 'local-discovery': Sets default values to fields affected by the server profile, enables discovery in local networks. @@ -1287,10 +1332,16 @@ DESCRIPTION 'test': Reduces external interference of IPFS daemon, this is useful when using the daemon in test environments. - 'test-cid-v1': - Makes UnixFS import produce CIDv1 with raw leaves, sha2-256 and 1 MiB chunks (max 174 links per file, 256 per HAMT node, switch dir to HAMT above 256KiB). - 'test-cid-v1-wide': - Makes UnixFS import produce CIDv1 with raw leaves, sha2-256 and 1MiB chunks and wider file DAGs (max 1024 links per every node type, switch dir to HAMT above 1MiB). + 'unixfs-v0-2015': + Legacy UnixFS import profile for backward-compatible CID generation. + Produces CIDv0 with no raw leaves, sha2-256, 256 KiB chunks, and + link-based HAMT size estimation. Use only when legacy CIDs are required. + See https://github.com/ipfs/specs/pull/499. Alias: legacy-cid-v0 + 'unixfs-v1-2025': + Recommended UnixFS import profile for cross-implementation CID determinism. + Uses CIDv1, raw leaves, sha2-256, 1 MiB chunks, 1024 links per file node, + 256 HAMT fanout, and block-based size estimation for HAMT threshold. + See https://github.com/ipfs/specs/pull/499 SUBCOMMANDS ipfs config profile apply - Apply profile to config. @@ -1407,10 +1458,10 @@ OPTIONS limits if needed. Default: true. --migrate bool - If true, assume yes at the migrate prompt. If false, assume no. - --enable-pubsub-experiment bool - DEPRECATED. - --enable-namesys-pubsub bool - Enable IPNS over pubsub. Implicitly - enables pubsub, overrides - Ipns.UsePubsub config. + --enable-pubsub-experiment bool - DEPRECATED CLI flag. Use + Pubsub.Enabled config instead. + --enable-namesys-pubsub bool - DEPRECATED CLI flag. Use + Ipns.UsePubsub config instead. --enable-mplex-experiment bool - DEPRECATED. --agent-version-suffix string - Optional suffix to the AgentVersion presented by `ipfs id` and exposed @@ -1605,7 +1656,7 @@ OPTIONS --fast-provide-wait bool - Block until the immediate provide completes before returning. Default: Import.FastProvideWait. --allow-big-block bool - Disable block size check and allow creation of - blocks bigger than 1MiB. WARNING: such blocks + blocks bigger than 2MiB. WARNING: such blocks won't be transferable over the standard bitswap. Default: false. @@ -1669,7 +1720,7 @@ OPTIONS --pin bool - Pin this object when adding. --hash string - Hash function to use. --allow-big-block bool - Disable block size check and allow creation of - blocks bigger than 1MiB. WARNING: such blocks + blocks bigger than 2MiB. WARNING: such blocks won't be transferable over the standard bitswap. Default: false. @@ -1708,7 +1759,7 @@ USAGE ipfs dag stat ... - Gets stats for a DAG. SYNOPSIS - ipfs dag stat [--progress=false] [--] ... + ipfs dag stat [--progress | -p] [--] ... ARGUMENTS @@ -1716,8 +1767,8 @@ ARGUMENTS OPTIONS - -p, --progress bool - Return progressive data while reading through the DAG. - Default: true. + -p, --progress bool - Show progress on stderr. Auto-detected if stderr is a + terminal. DESCRIPTION @@ -1868,6 +1919,10 @@ SUBCOMMANDS For more information about each command, use: 'ipfs diag --help' +EXPERIMENTAL SUBCOMMANDS + ipfs diag datastore - Low-level datastore inspection for debugging and + testing. + ``` @@ -1926,6 +1981,107 @@ ARGUMENTS