Repository files navigation

Stay up to date with changes by joining theofficial Discord and by keeping an eye onthereleases tab.

• Swarm-CLI
• Table of Contents
• Demo
  • Purchasing a Postage Stamp
  • Uploading a File
  • Creating an Identity
  • Uploading to a Feed
  • Upload file with ACT
  • Download file with ACT
  • Create grantees list
  • Get grantees list
  • Patch grantees list
• Description
  • Installation
    • From npm
    • From source
  • Usage
  • Commands
  • Example usage
  • Usability Features
    • Uploading Files, Folders, Websites, and Arbitrary Data from stdin
      • Files
      • Folders and Websites
      • Standard Input
    • Custom HTTP Headers
    • Autocomplete
    • Numerical Separator and Units
    • Stamp Picker
    • Identity Picker
    • Human Readable Topics
    • Manifest address scheme
    • Automating tasks with Swarm-CLI
      • Connectivity
      • Postage Stamps
      • Uploading
  • Config
  • Assignment priority
  • System environment
• Development
• Contribute
• Maintainers
• License

swarm-cli upload<file> --act --stamp<postage_batch_id>

swarm-cli download<swarm_hash><file> --act --act-history-address<swarm_history_address> --act-publisher<public_key>

swarm-cli grantee create grantees.json --stamp<postage_batch_id>

grantees.json:

{"grantees": ["02ceff1422a7026ba54ad89967d81f2805a55eb3d05f64eb5c49ea6024212b12e8","02ceff1422a7026ba54ad89967d81f2805a55eb3d05f64eb5c49ea6024212b12e9","02ceff1422a7026ba54ad89967d81f2805a55eb3d05f64eb5c49ea6024212b12ee"]}

swarm-cli grantee get<grantee_reference>

swarm-cli  grantee patch grantees-patch.json \    --reference<grantee_reference> \    --history<grantee_history_reference> \    --stamp<postage_batch_id>

grantees-patch.json:

{"add": ["02ceff1422a7026ba54ad89967d81f2805a55eb3d05f64eb5c49ea6024212b12e7"    ],"revoke": ["02ceff1422a7026ba54ad89967d81f2805a55eb3d05f64eb5c49ea6024212b12e9","02ceff1422a7026ba54ad89967d81f2805a55eb3d05f64eb5c49ea6024212b12ee"    ]}

Manage your Bee node and interact with the Swarm network via the CLI

The goal of this project is to handle most of the Swarm operations through CLI at some point in the future.

For the currently supported operations, see theCommands section.

Requires Node.js 18 or higher. It is recommended to useNVM to manage Node.js versions.

Warning! Installing Node.js via package managers (e.g.apt,yum,brew) may not work as expected, as they mayinstall an older version of Node.js.

Install globally:

npm install --global @ethersphere/swarm-cli

See theDevelopment section.

The general usage is to provide a command, optionally a subcommand, then arguments and options.

swarm-cli command [subcommand] <arguments> [options]

Running a command with the--help option prints out the usage of a command.

Runningswarm-cli without arguments prints the available commands:

Swarm CLI 2.11.0 - Manage your Bee node and interact with the Swarm network via the CLI█ Usage:swarm-cli COMMAND [OPTIONS]█ Available Groups:pinning    Pin, unpin and check pinned chunksidentity   Import, export and manage keypairs, identitiesfeed       Upload, update and view feedscheque     Deposit, withdraw and manage chequesstamp      Buy, list and show postage stampspss        Send, receive, or subscribe to PSS messagesmanifest   Operate on manifestsutility    Utility commands for managing walletsgrantee    Create, Get, Patch grantee listRun 'swarm-cli GROUP --help' to see available commands in a group█ Available Commands:upload      Upload file to Swarmdownload    Download arbitrary Swarm hashhash        Print the Swarm hash of a filestatus      Check Bee statusaddresses   Display the addresses of the Bee nodestake       Manages nodes stakeRun 'swarm-cli COMMAND --help' for more information on a command

Let's say we want to upload our website to Swarm and update a feed to point to the newest version. For updating a feedwe would need to sign it with an Ethereum key, so first we need to create one with theidentity create command:

swarm-cli identity create

This command will ask for a password. After that a new identity is created (namedmain). Now we can use this identityto sign updates. It's also possible to import and export Ethereum JSON V3 format identities that works with other apps(e.g. wallets).

Another requirement for uploading to the Swarm network is a valid postage batch, also called a postage stamp or simply astamp. Stamps need to be purchased with xBZZ tokens. We can use thestamp buy command to take care of this step. The--amount and--depth options alter the capacity of the postage stamp. For example, runningstamp buy --amount 1 --depth 20 will get back with a Stamp ID after a while. We will be using that with the--stampoption in commands which upload files, or write feeds.

For uploading to a feed we can use thefeed upload command. It expects the path of the folder (or file) we want toupload and as options it expectsidentity to be provided along with thepassword that belongs to it, as well as theearlier mentionedstamp.

swarm-cli feed upload path-to-be-uploaded --identity my-identity --password my-secret-password --stamp stamp-id

In this example we are uploading the content of thedist folder. If the uploading was successful the last printed linewill contain aFeed Manifest URL. This URL can be opened in the browser. If the uploaded folder contains anindex.html file then it will be automatically displayed when visiting the URL.

This URL will stay the same when we upload an updated version of the website. Because of this we can also put this URLinto a reverse proxy configuration or use the reference (the hex string after the/bzz/) in an ENS record. There ismore information about that in theBee documentation. The uploaded contentcan be found on the link in the line starting withURL. This will change every time the content is modified.

Useswarm-cli to upload a single file:

swarm-cli upload README.md

The command above will print a/bzz URL that may be opened in the browser. If the browser is able to handle the fileformat then the file is displayed, otherwise it will be offered to be downloaded.

swarm-cli also supports uploading folders with the sameupload command:

swarm-cli upload build/

This also yields a/bzz URL. If there is anindex.html present in the root of the folder,--index-document will beautomatically applied byswarm-cli. This option sets which file the browser should open for an empty path. You mayalso freely set--index-document during upload to change this.

You can pipe data from other commands toswarm-cli using the--stdin option.

curl -L https://picsum.photos/200 | swarm-cli --stdin --stamp [...]

Unlike other upload methods, this results in a/bytes URL, which cannot be displayed by browsers normally. You canstill share your hash and others can download it. However, with the--name option, you can give your arbitrary data afile name, andswarm-cli will attempt to determine the suitable content type for your data. Given it is successful,swarm-cli will print a/bzz URL instead of the/bytes URL, which is good to be displayed in browsers. Example:

curl -L https://picsum.photos/200 | swarm-cli --stdin --stamp [...] --name random.jpg

There is also a--content-type option if you want to adjust it manually:

curl -L https://picsum.photos/200 | swarm-cli --stdin --stamp [...] --name random --content-type image/jpeg

Please note that stdin is reserved for the data you are uploading, so interactive features are disabled during thistime. Because of that,--stamp must be passed beforehand. You may create an alias for grabbing the ID of the leastused postage stamp:

alias st='swarm-cli stamp list --least-used --limit 1 --hide-usage --quiet'

Leveraging the alias above, you can use a shortcut for uploading from stdin:

curl -L https://picsum.photos/200 | swarm-cli --stdin --stamp $(st)

Similarly tocurl, you may use the--header or-H option to specify as many additional headers as you want, whichwill be sent with all requests:

swarm-cli upload README.md -H "Authorization: [...]" -H "X-Custom-Header: Your Value"

swarm-cli has support for autocomplete inbash,zsh andfish. This turns on<tab><tab> suggestions which cancomplete commands, paths and options for you.

To enable it, you need to install it once via two options:

• Runningswarm-cli --generate-completion and following the instructions there
• Runningswarm-cli --install-completion which automatically appends the completion script to your configuration file

Warning! If you start a subshell (e.g. runningbash fromzsh), yourSHELL env variable would still be the oldvalue! The generation and completion script cannot detect your shell accurately in that case, so please setSHELLmanually. It is generally advised to run--generate-completion first to ensure the shell and the paths are properlydetected.

Example:

$ SHELL=zsh$ swarm-cli --generate-completionYour shell is: zshFound configuration file path: /Users/Swarm/.zshrcAppend the completion script below to your configuration file to enable autocomplete.You need to source your configuration, or restart your shell, to load the changes.<script>

As most of the units are specified in wei and PLUR - the smallest denominations of currencies - they are a bit difficultto write out.

To aid this, you may use underscores (_) andK,M,B andT units to make your numbers more comprehensible.

Example:

swarm-cli stamp buy --amount 10M --depth 17 --gas-price 10_000_000_000_000

You may combine the two:100_000T.

Unless you are running in--quiet mode, some options are not hard-required.

Look for hints in the--help sections. Take theupload command for example:

█ Required Options:   --stamp   ID of the postage stamp to use  [required when quiet][string]

That means, you don't have to provide the postage stamp ID beforehand. Simply runningswarm-cli upload <path> willprompt you with an interactive stamp picker:

? Please select a stamp for this action.  Stamp ID                                                         Utilization (Use arrow keys)❯ b9d5bb548c2c209cb99cbb27b0bef59b8f0cd3558363e307f45177b5a64ad0c8 (1)

Similarly to Stamp Picker, when an identity is not provided, an interactive picker will be prompted.

Take the commandfeed upload for example. Albeit it takes quite a lot of options, you can run it with typing as littleasfeed upload <path>.

swarm-cli will take you through some prompts to interactively specify all required options, such asidentity,password of the identity, and the mandatorystamp.

Passing identities is also tolerant to errors, so if you provide one which does not exist, the output will tell you andyou can correct it:

The provided identity does not exist. Please select one that exists.? Please select an identity for this action (Use arrow keys)❯ main

You may need to pass topics on multiple occasions - for example, when uploading to feeds.

Topics are 32-byte long identifiers, so you need 64 characters to write them out in hexadecimal string format.

You can do that with the--topic or-t option, or alternatively take a shortcut and use a human readable stringwhich will be hashed byswarm-cli for your convenience. It is available via the--topic-string or-T option.

Example:

swarm-cli feed upload [...] -T "Awesome Swarm Website"

This is also indicated in the--help section:

-t --topic         32-byte long identifier in hexadecimal format    [hex-string][default all zeroes]-T --topic-string  Construct the topic from human readable strings                          [string]Only one is required: [topic] or [topic-string]

Themanifest commands enable low-level operation on manifests. These always require a root manifest reference (hash)argument as the input. Some commands, however, work with subparts of the manifest. A few examples are: downloading onlya folder from a manifest, listing files only under a specific path in a manifest, and adding files or folders not to theroot of the manifest, but under some path.

These can be achieved by using thebzz://<hash>/<path> scheme in the<address> argument as follows:

List entries under the/command/pss prefix in manifest1512546a3f4d0fea9f35fa1177486bdfe2bc2536917ad5012ee749604a7b425f

swarm-cli manifest list bzz://1512546a3f4d0fea9f35fa1177486bdfe2bc2536917ad5012ee749604a7b425f/command/pss

DownloadREADME.md from manifest1512546a3f4d0fea9f35fa1177486bdfe2bc2536917ad5012ee749604a7b425f

swarm-cli manifest download bzz://1512546a3f4d0fea9f35fa1177486bdfe2bc2536917ad5012ee749604a7b425f/README.md

Note: Thebzz:// protocol can be omitted.

Runningswarm-cli with the flag--quiet (or-q for short) disables all interactive features, and makes commandsprint information in an easily parsable format. The exit code also indicates whether running the command was successfulor not. These may be useful for automating tasks both in CI environments and in your terminal too.

Below you will find a few snippets to give an idea how it can be used to compose tasks.

Exit if not all status checks succeed:

swarm-cli status -q || exit 1

Check Bee API connection, compatibility does not matter:

swarm-cli status -q | head -n 1 | grep "^OK"

Grab the first postage stamp:

swarm-cli stamp list --limit 1 --quiet --hide-usage

Grab the least used postage stamp:

swarm-cli stamp list --limit 1 --quiet --hide-usage --least-used

List all postage stamps with zero utilization:

swarm-cli stamp list --max-usage 0 --quiet --hide-usage

Sort postage stamps based on utilization (least utilized comes first):

swarm-cli stamp list --least-used --quiet

Upload a file with the least utilized postage stamp (that has at most 50% usage):

STAMP=$(swarm-cli stamp list --max-usage 50 --least-used --limit 1 --quiet --hide-usage)swarm-cli upload -q README.md --stamp $STAMP

The configuration file is placed in a hidden folder namedswarm-cli.

In case of Unix-based systems this config path will be:$HOME/.swarm-cli

On Windows systems:$HOME\AppData\swarm-cli

The configuration file is saved with600 file permission.

On first run, this configuration will be generated with default values, that you are able to change on your demand underthe before mentioned path.

It is possible to set value of particular parameters in different ways.

The assignment priority of how option gets its value in question is the following:

1. passed CLI option value (with e.g.--option-example-1)
2. env variable for that option in form of eitherOPTION_EXAMPLE_1 orSWARM_CLI_OPTION_EXAMPLE_1 (if it isavailable)
3. CLI configuration value of that option (if it is available)
4. option's default fallback value (or it is required to define by #1)

With specific system environment variables you can alter the behaviour of the CLI

• BEE_API_URL - API URL of Bee client
• SWARM_CLI_CONFIG_FOLDER - full path to a configuration folder
• SWARM_CLI_CONFIG_FILE - configuration file name, defaults to config.json

After the project has been cloned, the dependencies must be installed. Run the following in the project folder:

 $ npm install

Then you need to compile the TypeScript code:

 $ npm run build

To make the localswarm-cli files in thedist/ directory available as a global package:

 $ npm link

If all went well you should be able to runswarm-cli.

Ifnpm link fails, or you don't want to install anything, then you can usenode dist/src/index.js to runswarm-clifrom the checked out directory.

There are some ways you can make this module better:

• Consult ouropen issues and take on one of them
• Help our tests reach 100% coverage!

• Cafe137

See what "Maintainer" meanshere.

BSD-3-Clause