Commands
Configuration Commands
Get Current BTFS Node Config
USAGE
$ btfs config show - Output config file contents.
SYNOPSIS
$ btfs config show
DESCRIPTION
NOTE: For security reasons, this command will omit your private key. If you would like to make a full backup of your config (private key included), you must copy the config file from your repo.
EXAMPLE
$ btfs config show #This will retrieve the full content of config file under .btfs repository excluding Seedphrase and private key
Basic commands
Initialize BTFS Node + Repo
USAGE
$ btfs init [<default-config>] - Initializes btfs config file.
SYNOPSIS
$ btfs init [--bits=<bits> | -b] [--empty-repo | -e]
[--profile=<profile> | -p] [--key=<key> | -k]
[--import=<import> | -i] [--rm-on-unpin | -r] [--seed=<seed> | -s]
[--] [<default-config>]
ARGUMENTS
[<default-config>] - Initialize with the given configuration.
OPTIONS
-b, --bits int - Number of bits to use in the generated RSA
private key. Default: 2048.
-e, --empty-repo bool - Don't add and pin help files to the local storage.
-p, --profile string - Apply profile settings to config. Multiple
profiles can be separated by ','.
-k, --key string - Key generation algorithm, e.g. RSA, Ed25519,
Secp256k1, ECDSA, BIP39. By default is BIP39.
-i, --import string - Import TRON private key to generate btfs PeerID.
-r, --rm-on-unpin bool - Remove unpinned files. Default: false.
-s, --seed string - Import seed phrase.
DESCRIPTION
Initializes btfs configuration files and generates a new keypair.
If you are going to run BTFS in server environment, you may want to
initialize it using 'server' profile.
For the list of available profiles see 'btfs config profile --help'
btfs uses a repository in the local file system. By default, the repo is
located at ~/.btfs. To change the repo location, set the $BTFS_PATH
environment variable:
export BTFS_PATH=/path/to/btfsrepo
EXAMPLE
$ btfs init -p storage-host // Under "Experimental", the StorageHostEnabled setting is set to true
$ btfs init -s "YOUR SEED HERE" //Initialize a node using a previously created BTFS node
BTFS daemon (Start a long-running daemon process)
USAGE
$ btfs daemon - Run a network-connected BTFS node.
SYNOPSIS
$ btfs daemon [--init] [--init-config=<init-config>] [--init-profile=<init-profile>] [--routing=<routing>]
[--mount] [--writable] [--mount-btfs=<mount-btfs>] [--mount-btns=<mount-btns>] [--unrestricted-api]
[--disable-transport-encryption] [--enable-gc] [--manage-fdlimit=false] [--migrate=false]
[--enable-pubsub-experiment] [--enable-namesys-pubsub] [--enable-mplex-experiment] [--hval=<hval>]
[--dc] [--enable-startup-test] [--swarm-port=<swarm-port>]
[--deployment-gasPrice=<deployment-gasPrice>] [--chain-id=<chain-id>]
OPTIONS
--init bool - Initialize btfs with default settings if not already initialized.
--init-config string - Path to existing configuration file to be loaded during --init.
--init-profile string - Configuration profiles to apply for --init. See btfs init --help for
more.
--routing string - Overrides the routing option. Default: default.
--mount bool - Mounts BTFS to the filesystem.
--writable bool - Enable writing objects (with POST, PUT and DELETE).
--mount-btfs string - Path to the mountpoint for BTFS (if using --mount). Defaults to config
setting.
--mount-btns string - Path to the mountpoint for BTNS (if using --mount). Defaults to config
setting.
--unrestricted-api bool - Allow API access to unlisted hashes.
--disable-transport-encryption bool - Disable transport encryption (for debugging protocols).
--enable-gc bool - Enable automatic periodic repo garbage collection.
--manage-fdlimit bool - Check and raise file descriptor limits if needed. Default: true.
--migrate bool - If true, assume yes at the migrate prompt. If false, assume no. Default:
true.
--enable-pubsub-experiment bool - Instantiate the btfs daemon with the experimental pubsub feature enabled.
--enable-namesys-pubsub bool - Enable BTNS record distribution through pubsub; enables pubsub.
--enable-mplex-experiment bool - DEPRECATED.
--hval string - H-value identifies the BitTorrent client this daemon is started by. None
if not started by a BitTorrent client.
--dc bool - Allow BTFS to collect and send out node statistics.
--enable-startup-test bool - Allow BTFS to perform start up test. Default: false.
--swarm-port string - Override existing announced swarm address with external port in the
format of [WAN:LAN].
--deployment-gasPrice string - gas price in unit to use for deployment and funding.
--chain-id string - The ID of blockchain to deploy.
DESCRIPTION
The daemon will start listening on ports on the network, which are
documented in (and can be modified through) 'btfs config Addresses'.
For example, to change the 'Gateway' port:
btfs config Addresses.Gateway /ip4/127.0.0.1/tcp/8082
The API address can be changed the same way:
btfs config Addresses.API /ip4/127.0.0.1/tcp/5002
Make sure to restart the daemon after changing addresses.
By default, the gateway is only accessible locally. To expose it to
other computers in the network, use 0.0.0.0 as the ip address:
btfs config Addresses.Gateway /ip4/0.0.0.0/tcp/8080
Be careful if you expose the API. It is a security risk, as anyone could
control your node remotely. If you need to control the node remotely,
make sure to protect the port as you would other services or database
(firewall, authenticated proxy, etc).
HTTP Headers
btfs supports passing arbitrary headers to the API and Gateway. You can
do this by setting headers on the API.HTTPHeaders and Gateway.HTTPHeaders
keys:
btfs config --json API.HTTPHeaders.X-Special-Header '["so special :)"]'
btfs config --json Gateway.HTTPHeaders.X-Special-Header '["so special :)"]'
Note that the value of the keys is an _array_ of strings. This is because
headers can have more than one value, and it is convenient to pass through
to other libraries.
CORS Headers (for API)
You can setup CORS headers the same way:
btfs config --json API.HTTPHeaders.Access-Control-Allow-Origin '["example.com"]'
btfs config --json API.HTTPHeaders.Access-Control-Allow-Methods '["PUT", "GET", "POST"]'
btfs config --json API.HTTPHeaders.Access-Control-Allow-Credentials '["true"]'
Shutdown
To shut down the daemon, send a SIGINT signal to it (e.g. by pressing 'Ctrl-C')
or send a SIGTERM signal to it (e.g. with 'kill'). It may take a while for the
daemon to shutdown gracefully, but it can be killed forcibly by sending a
second signal.
BTFS_PATH environment variable
btfs uses a repository in the local file system. By default, the repo is
located at ~/.btfs. To change the repo location, set the $BTFS_PATH
environment variable:
export BTFS_PATH=/path/to/btfsrepo
Routing
BTFS by default will use a DHT for content routing. There is a highly
experimental alternative that operates the DHT in a 'client only' mode that
can be enabled by running the daemon as:
btfs daemon --routing=dhtclient
This will later be transitioned into a config option once it gets out of the
'experimental' stage.
DEPRECATION NOTICE
Previously, btfs used an environment variable as seen below:
export API_ORIGIN="http://localhost:8888/"
This is deprecated. It is still honored in this version, but will be removed
in a future version, along with this notice. Please move to setting the HTTP
Headers.
EXAMPLE
$btfs daemon --chain-id 199 //Starts a new daemon process using BTTC mainnet configuration, this is the normal way of executing a BTFS daemon up to BTFS v2.1.3
Add file to BTFS repository
USAGE
$ btfs add <path>... - Add a file or directory to btfs.
SYNOPSIS
$btfs add [--recursive | -r] [--dereference-args] [--stdin-name=<stdin-name>] [--hidden | -H]
[--ignore=<ignore>]... [--ignore-rules-path=<ignore-rules-path>] [--quiet | -q] [--quieter | -Q]
[--silent] [--progress | -p] [--trickle | -t] [--only-hash | -n] [--wrap-with-directory | -w]
[--chunker=<chunker> | -s] [--pin=false] [--raw-leaves] [--nocopy] [--fscache] [-v=<v>] [--hash=<hash>]
[--inline] [--inline-limit=<inline-limit>] [--meta=<meta> | -m] [--encrypt] [--public-key=<public-key>]
[--peer-id=<peer-id>] [--pin-duration-count=<pin-duration-count> | -d] [--] <path>...
ARGUMENTS
<path>... - The path to a file to be added to btfs.
OPTIONS
-r, --recursive bool - Add directory paths recursively.
--dereference-args bool - Symlinks supplied in arguments are dereferenced.
--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.
--ignore array - A rule (.gitignore-stype) defining which file(s) should be ignored (variadic,
experimental).
--ignore-rules-path string - A path to a file with .gitignore-style ignore rules (experimental).
-q, --quiet bool - Write minimal output.
-Q, --quieter bool - Write only final hash.
--silent bool - Write no output.
-p, --progress bool - Stream progress data.
-t, --trickle bool - Use trickle-dag format for dag generation.
-n, --only-hash bool - Only chunk and hash - do not write to disk.
-w, --wrap-with-directory bool - Wrap files with a directory object.
-s, --chunker string - Chunking algorithm, size-[bytes], rabin-[min]-[avg]-[max], buzhash or
reed-solomon-[#data]-[#parity]-[size]. Default: size-262144.
--pin bool - Pin this object when adding. Default: true.
--raw-leaves bool - Use raw blocks for leaf nodes. (experimental).
--nocopy bool - Add the file using filestore. Implies raw-leaves. (experimental).
--fscache bool - Check the filestore for pre-existing blocks. (experimental).
-v int - CID version. Defaults to 0 unless an option that depends on CIDv1 is passed.
(experimental).
--hash string - Hash function to use. Implies CIDv1 if not sha2-256. (experimental). Default:
sha2-256.
--inline bool - Inline small blocks into CIDs. (experimental).
--inline-limit int - Maximum block size to inline. (experimental). Default: 32.
-m, --meta string - Token metadata in JSON string.
--encrypt bool - Encrypt the file.
--public-key string - The public key to encrypt the file.
--peer-id string - The peer id to encrypt the file.
-d, --pin-duration-count int - Duration for which the object is pinned in days. Default: 0.
DESCRIPTION
Adds contents of <path> to btfs. Use -r to add directories.
Note that directories are added recursively, to form the btfs
MerkleDAG.
If the daemon is not running, it will just add locally.
If the daemon is started later, it will be advertised after a few
seconds when the reprovider runs.
The wrap option, '-w', wraps the file (or files, if using the
recursive option) in a directory. This directory contains only
the files which have been added, and means that the file retains
its filename. For example:
> btfs add example.jpg
added QmbFMke1KXqnYyBBWxB74N4c5SBnJMVAiMNRcGu6x1AwQH example.jpg
> btfs add example.jpg -w
added QmbFMke1KXqnYyBBWxB74N4c5SBnJMVAiMNRcGu6x1AwQH example.jpg
added QmaG4FuMqEBnQNn3C8XJ5bpW8kLs7zq2ZXgHptJHbKDDVx
You can now refer to the added file in a gateway, like so:
/btfs/QmaG4FuMqEBnQNn3C8XJ5bpW8kLs7zq2ZXgHptJHbKDDVx/example.jpg
The chunker option, '-s', specifies the chunking strategy that dictates
how to break files into blocks. Blocks with same content can
be deduplicated. Different chunking strategies will produce different
hashes for the same file. The default is a fixed block size of
256 * 1024 bytes, 'size-262144'. Alternatively, you can use the
Rabin fingerprint chunker for content defined chunking by specifying
rabin-[min]-[avg]-[max] (where min/avg/max refer to the desired
chunk sizes in bytes), e.g. 'rabin-262144-524288-1048576'.
Buzhash or Rabin fingerprint chunker for content defined chunking by
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'.
For replicated files intended for host storage, reed-solomon should be
used with default settings. It is also supported to customize data and
parity shards using reed-solomon-[#data]-[#parity]-[size].
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.
> btfs add --chunker=size-2048 btfs-logo.svg
added QmafrLBfzRLV4XSH1XcaMMeaXEUhDJjmtDfsYU95TrWG87 btfs-logo.svg
> btfs add --chunker=rabin-512-1024-2048 btfs-logo.svg
added Qmf1hDN65tR55Ubh2RN1FPxr69xq3giVBz1KApsresY8Gn btfs-logo.svg
You can now check what blocks have been created by:
> btfs object links QmafrLBfzRLV4XSH1XcaMMeaXEUhDJjmtDfsYU95TrWG87
QmY6yj1GsermExDXoosVE3aSPxdMNYr6aKuw3nA8LoWPRS 2059
Qmf7ZQeSxq2fJVJbCmgTrLLVN9tDR9Wy5k75DxQKuz5Gyt 1195
> btfs object links Qmf1hDN65tR55Ubh2RN1FPxr69xq3giVBz1KApsresY8Gn
QmY6yj1GsermExDXoosVE3aSPxdMNYr6aKuw3nA8LoWPRS 2059
QmerURi9k4XzKCaaPbsK6BL5pMEjF7PGphjDvkkjDtsVf3 868
QmQB28iwSriSUSMqG2nXDTLtdPHgWb4rebBrU7Q1j4vxPv 338
Finally, a note on hash determinism. While not guaranteed, adding the same
file/directory with the same flags will almost always result in the same output
hash. However, almost all of the flags provided by this command (other than pin,
only-hash, and progress/status related flags) will change the final hash.
BTFS cat (Concatenate BTFS files and print on the standard output)
USAGE
$ btfs cat <btfs-path>... - Show BTFS object data.
SYNOPSIS
$ btfs cat [--offset=<offset> | -o] [--length=<length> | -l] [--meta | -m] [--decrypt | -d]
[--private-key=<private-key> | --pk] [--] <btfs-path>...
ARGUMENTS
<btfs-path>... - The path to the BTFS object(s) to be outputted.
OPTIONS
-o, --offset int64 - Byte offset to begin reading from.
-l, --length int64 - Maximum number of bytes to read.
-m, --meta bool - Display token metadata.
-d, --decrypt bool - Decrypt the file.
--pk, --private-key string - The private key to decrypt file.
DESCRIPTION
Displays the data contained by an BTFS or BTNS object(s) at the given path.
EXAMPLE
$ btfs cat /btfs/QmafrLBfzRLV4XSH1XcaMMeaXEUhDJjmtDfsYU95TrWG87 //If this Qmhash is a txt file it will output its content to terminal window
BTFS Get (Download a BTFS objects)
USAGE
$ btfs get <btfs-path> - Download BTFS objects.
SYNOPSIS
$ btfs get [--output=<output> | -o] [--archive | -a] [--compress | -C]
[--compression-level=<compression-level> | -l] [--meta | -m] [--decrypt | -d]
[--private-key=<private-key> | --pk] [--repair-shards=<repair-shards> | --rs] [--quiet | -q] [--]
<btfs-path>
ARGUMENTS
<btfs-path> - The path to the BTFS object(s) to be outputted.
OPTIONS
-o, --output string - The path where the output should be stored.
-a, --archive bool - Output a TAR archive.
-C, --compress bool - Compress the output with GZIP compression.
-l, --compression-level int - The level of compression (1-9).
-m, --meta bool - Display token metadata.
-d, --decrypt bool - Decrypt the file.
--pk, --private-key string - The private key to decrypt file.
--rs, --repair-shards string - Repair the list of shards. Multihashes separated by ','.
-q, --quiet bool - Quiet mode: perform get operation without writing to anywhere. Same as using -o
/dev/null.
DESCRIPTION
Stores to disk the data contained an BTFS or BTNS object(s) at the given path.
By default, the output will be stored at './<btfs-path>', but an alternate
path can be specified with '--output=<path>' or '-o=<path>'.
To output a TAR archive instead of unpacked files, use '--archive' or '-a'.
To compress the output with GZIP compression, use '--compress' or '-C'. You
may also specify the level of compression by specifying '-l=<1-9>'.
To output just the metadata of this BTFS node, use '--meta' or '-m'.
To repair missing shards of a Reed-Solomon encoded file, use '--repair-shards' or '-rs'.
If '--meta' or '-m' is enabled, this option is ignored.
###BTFS List (List directories & files)
USAGE
$ btfs ls <btfs-path>... - List directory contents for Unix filesystem objects.
SYNOPSIS
$ btfs ls [--headers | -v] [--resolve-type=false] [--size=false] [--stream | -s] [--] <btfs-path>...
ARGUMENTS
<btfs-path>... - The path to the BTFS object(s) to list links from.
OPTIONS
-v, --headers bool - Print table headers (Hash, Size, Name).
--resolve-type bool - Resolve linked objects to find out their types. Default: true.
--size bool - Resolve linked objects to find out their file size. Default: true.
-s, --stream bool - Enable experimental streaming of directory entries as they are traversed.
DESCRIPTION
Displays the contents of an BTFS or BTNS object(s) at the given path, with
the following format:
<link base58 hash> <link size in bytes> <link name>
The JSON output contains type information.
EXAMPLE
$ btfs ls btfs/QmafrLBfzRLV4XSH1XcaMMeaXEUhDJjmtDfsYU95TrWG87 //Outputs directories and files under the given BTFS path
Data Structure Commands
File Copy to Mutable File System
USAGE
$ btfs files cp <source> <dest> - Copy any BTFS files and directories into
MFS (or copy within MFS).
SYNOPSIS
$ btfs files cp [--] <source> <dest>
ARGUMENTS
<source> - Source IPFS or MFS path to copy.
<dest> - Destination within MFS.
DESCRIPTION
"btfs files cp" can be used to copy any BTFS file or directory (usually in the
form /btfs/<CID>, but also any resolvable path), into the Mutable File System
(MFS).
It can also be used to copy files within MFS, but in the case when an
IPFS-path matches an existing MFS path, the BTFS path wins.
In order to add content to MFS from disk, you can use "btfs add" to obtain the
BTFS Content Identifier and then "btfs files cp" to copy it into MFS:
EXAMPLE
$ btfs add --quieter --pin=false <your file>
# ...
# ... outputs the root CID at the end
$ btfs cp /btfs/<CID> /your/desired/mfs/path
Host Commands
Storage Commands
Wallet & BTTC Commands
Get Wallet Balance (BTFS 1.6 Compatibility)
USAGE
$ btfs wallet balance - BTFS wallet balance
SYNOPSIS
$ btfs wallet balance
OPTIONS
unit is µBTT (=0.000001BTT)
DESCRIPTION
Query BTFS wallet balance in ledger and block chain.
EXAMPLE
$ btfs wallet balance #This will retrieve the amount of BTT in your wallet
Swap BTT to WBTT
USAGE
$ btfs bttc btt2wbtt <amount> - Swap BTT to WBTT at you bttc address
SYNOPSIS
$ btfs bttc btt2wbtt [--] <amount>
ARGUMENTS
<amount> - amount you want to swap
EXAMPLE
$ btfs bttc btt2wbtt 100000000 #This will swap 100 BTT to 100 WBTT in your own BTTC wallet
Swap WBTT to BTT
USAGE
$ btfs bttc wbtt2btt <amount> - Swap WBTT to BTT at you bttc address
SYNOPSIS
$ btfs bttc wbtt2btt [--] <amount>
ARGUMENTS
<amount> - amount you want to swap
EXAMPLE
$ btfs bttc wbtt2btt 100000000 #This will swap 100 WBTT to 100 BTT in your own BTTC wallet
Send BTT to another BTTC address
USAGE
$ btfs bttc send-btt-to <addr> <amount> - Transfer your BTT to other bttc address
SYNOPSIS
$ btfs bttc send-btt-to [--] <addr> <amount>
ARGUMENTS
<addr> - target bttc address
<amount> - amount you want to send
EXAMPLE
$ btfs bttc send-btt-to 0xB3D96310b4831f14D294F86d1224077502Aeb27C 100000000 #This will send 100 BTT to 0xB3D96310b4831f14D294F86d1224077502Aeb27C address
Send WBTT to another BTTC address
USAGE
$ btfs bttc send-wbtt-to <addr> <amount> - Transfer your WBTT to other bttc address
SYNOPSIS
$ btfs bttc send-wbtt-to [--] <addr> <amount>
ARGUMENTS
<addr> - target bttc address
<amount> - amount you want to send
EXAMPLE
$ btfs bttc send-wbtt-to 0xB3D96310b4831f14D294F86d1224077502Aeb27C 100000000 #This will send 100 WBTT to 0xB3D96310b4831f14D294F86d1224077502Aeb27C address
Cheque commands
Get Cheque Balance (BTT)
USAGE
$ btfs cheque bttbalance <addr> - Get btt balance by addr.
SYNOPSIS
$ btfs cheque bttbalance [--] <addr>
ARGUMENTS
<addr> - bttc account address
EXAMPLE
$ btfs cheque bttbalance 0xB3D96310b4831f14D294F86d1224077502Aeb27C #This will retrieve your current account balance (BTT)