lbry-sdk/docs/cli.md

962 lines
28 KiB
Markdown
Raw Normal View History

2017-06-09 18:14:03 +02:00
# LBRY Command Line Documentation
## blob_announce_all
```text
Announce all blobs to the DHT
Usage:
blob_announce_all
Returns:
(str) Success/fail message
```
## blob_delete
```text
Delete a blob
Usage:
blob_delete (<blob_hash> | --blob_hash=<blob_hash)
Returns:
(str) Success/fail message
```
## blob_get
```text
Download and return a blob
Usage:
blob_get (<blob_hash> | --blob_hash=<blob_hash>) [--timeout=<timeout>]
[--encoding=<encoding>] [--payment_rate_manager=<payment_rate_manager>]
Options:
--timeout=<timeout> : timeout in number of seconds
--encoding=<encoding> : by default no attempt at decoding is made,
can be set to one of the
following decoders:
'json'
--payment_rate_manager=<payment_rate_manager> : if not given the default payment rate
manager will be used.
supported alternative rate managers:
'only-free'
Returns
(str) Success/Fail message or (dict) decoded data
```
## blob_list
```text
Returns blob hashes. If not given filters, returns all blobs known by the blob manager
Args:
'uri' (optional): (str) filter by blobs in stream for winning claim
'stream_hash' (optional): (str) filter by blobs in given stream hash
'sd_hash' (optional): (str) filter by blobs in given sd hash
'needed' (optional): (bool) only return needed blobs
'finished' (optional): (bool) only return finished blobs
'page_size' (optional): (int) limit number of results returned
'page' (optional): (int) filter to page x of [page_size] results
Returns:
(list) List of blob hashes
```
## blob_reflect_all
```text
Reflects all saved blobs
Usage:
blob_reflect_all
Returns:
(bool) true if successful
```
## block_show
```text
Get contents of a block
Usage:
block_show (<blockhash> | --blockhash=<blockhash>) | (<height> | --height=<height>)
Options:
<blockhash>, --blockhash=<blockhash> : hash of the block to look up
<height>, --height=<height> : height of the block to look up
Returns:
(dict) Requested block
```
## channel_list_mine
```text
Get my channels
Usage:
channel_list_mine
Returns:
(list) ClaimDict
```
## channel_new
```text
Generate a publisher key and create a new '@' prefixed certificate claim
Usage:
channel_new (<channel_name> | --channel_name=<channel_name>)
(<amount> | --amount=<amount>)
Returns:
(dict) Dictionary containing result of the claim
{
'tx' : (str) hex encoded transaction
'txid' : (str) txid of resulting claim
'nout' : (int) nout of the resulting claim
'fee' : (float) fee paid for the claim transaction
'claim_id' : (str) claim ID of the resulting claim
}
```
## claim_abandon
```text
Abandon a name and reclaim credits from the claim
Usage:
claim_abandon (<claim_id> | --claim_id=<claim_id>)
Return:
(dict) Dictionary containing result of the claim
{
txid : (str) txid of resulting transaction
fee : (float) fee paid for the transaction
}
```
## claim_list
```text
2017-06-16 01:55:44 +02:00
List current claims and information about them for a given name
2017-06-09 18:14:03 +02:00
Usage:
claim_list (<name> | --name=<name>)
Returns
(dict) State of claims assigned for the name
{
'claims': (list) list of claims for the name
[
{
'amount': (float) amount assigned to the claim
'effective_amount': (float) total amount assigned to the claim,
including supports
'claim_id': (str) claim ID of the claim
'height': (int) height of block containing the claim
'txid': (str) txid of the claim
'nout': (int) nout of the claim
'supports': (list) a list of supports attached to the claim
'value': (str) the value of the claim
},
]
'supports_without_claims': (list) supports without any claims attached to them
'last_takeover_height': (int) the height of last takeover for the name
}
```
2017-06-16 01:55:44 +02:00
## claim_list_by_channel
```text
Get paginated claims in a channel specified by a channel uri
Usage:
claim_list_by_channel (<uri> | --uri=<uri>) [<uris>...] [--page=<page>]
[--page_size=<page_size>]
Options:
--page=<page> : which page of results to return where page 1 is the first
page, defaults to no pages
--page_size=<page_size> : number of results in a page, default of 10
Returns:
{
resolved channel uri: {
If there was an error:
'error': (str) error message
'claims_in_channel_pages': total number of pages with <page_size> results,
If a page of results was requested:
'returned_page': page number returned,
'claims_in_channel': [
{
'absolute_channel_position': (int) claim index number in sorted list of
claims which assert to be part of the
channel
'address': (str) claim address,
'amount': (float) claim amount,
'effective_amount': (float) claim amount including supports,
'claim_id': (str) claim id,
'claim_sequence': (int) claim sequence number,
'decoded_claim': (bool) whether or not the claim value was decoded,
'height': (int) claim height,
'depth': (int) claim depth,
'has_signature': (bool) included if decoded_claim
'name': (str) claim name,
'supports: (list) list of supports [{'txid': txid,
'nout': nout,
'amount': amount}],
'txid': (str) claim txid,
'nout': (str) claim nout,
'signature_is_valid': (bool), included if has_signature,
'value': ClaimDict if decoded, otherwise hex string
}
],
}
}
```
2017-06-09 18:14:03 +02:00
## claim_list_mine
```text
List my name claims
Usage:
claim_list_mine
Returns
(list) List of name claims owned by user
[
{
'address': (str) address that owns the claim
'amount': (float) amount assigned to the claim
'blocks_to_expiration': (int) number of blocks until it expires
'category': (str) "claim", "update" , or "support"
'claim_id': (str) claim ID of the claim
'confirmations': (int) number of blocks of confirmations for the claim
'expiration_height': (int) the block height which the claim will expire
'expired': (bool) true if expired, false otherwise
'height': (int) height of the block containing the claim
'is_spent': (bool) true if claim is abandoned, false otherwise
'name': (str) name of the claim
'txid': (str) txid of the cliam
'nout': (int) nout of the claim
'value': (str) value of the claim
},
]
```
## claim_new_support
```text
Support a name claim
Usage:
claim_new_support (<name> | --name=<name>) (<claim_id> | --claim_id=<claim_id>)
(<amount> | --amount<amount>)
Return:
(dict) Dictionary containing result of the claim
{
txid : (str) txid of resulting support claim
nout : (int) nout of the resulting support claim
fee : (float) fee paid for the transaction
}
```
2017-06-16 01:55:44 +02:00
## claim_send_to_address
```text
Send a name claim to an address
Usage:
claim_send_to_address (<claim_id> | --claim_id=<claim_id>)
(<address> | --address=<address>)
[<amount> | --amount=<amount>]
Options:
<amount> : Amount of credits to claim name for, defaults to the current amount
on the claim
```
2017-06-09 18:14:03 +02:00
## claim_show
```text
Resolve claim info from a LBRY name
Usage:
claim_show <name> [<txid> | --txid=<txid>] [<nout> | --nout=<nout>]
[<claim_id> | --claim_id=<claim_id>]
Options:
<txid>, --txid=<txid> : look for claim with this txid
<nout>, --nout=<nout> : look for claim with this nout
<claim_id>, --claim_id=<claim_id> : look for claim with this claim id
Returns:
(dict) Dictionary contaning claim info, (bool) false if claim is not
resolvable
{
'txid': (str) txid of claim
'nout': (int) nout of claim
'amount': (float) amount of claim
'value': (str) value of claim
'height' : (int) height of claim takeover
'claim_id': (str) claim ID of claim
'supports': (list) list of supports associated with claim
}
```
## cli_test_command
```text
This command is only for testing the CLI argument parsing
Usage:
2017-06-16 01:55:44 +02:00
cli_test_command [-a] [-b] (<pos_arg> | --pos_arg=<pos_arg>)
2017-06-09 18:14:03 +02:00
[<pos_args>...] [--pos_arg2=<pos_arg2>]
[--pos_arg3=<pos_arg3>]
Options:
2017-06-16 01:55:44 +02:00
-a, --a_arg : a arg
-b, --b_arg : b arg
2017-06-09 18:14:03 +02:00
<pos_arg2>, --pos_arg2=<pos_arg2> : pos arg 2
<pos_arg3>, --pos_arg3=<pos_arg3> : pos arg 3
Returns:
pos args
```
## commands
```text
Return a list of available commands
Usage:
commands
Returns:
(list) list of available commands
```
## daemon_stop
```text
Stop lbrynet-daemon
Usage:
daemon_stop
Returns:
(string) Shutdown message
```
## file_delete
```text
Delete a LBRY file
Usage:
2017-06-16 01:55:44 +02:00
file_delete [-f] [--delete_all] [--sd_hash=<sd_hash>] [--file_name=<file_name>]
2017-06-09 18:14:03 +02:00
[--stream_hash=<stream_hash>] [--claim_id=<claim_id>]
[--outpoint=<outpoint>] [--rowid=<rowid>]
[--name=<name>]
Options:
2017-06-16 01:55:44 +02:00
-f, --delete_from_download_dir : delete file from download directory,
instead of just deleting blobs
--delete_all : if there are multiple matching files,
allow the deletion of multiple files.
Otherwise do not delete anything.
--sd_hash=<sd_hash> : delete by file sd hash
--file_name<file_name> : delete by file name in downloads folder
--stream_hash=<stream_hash> : delete by file stream hash
--claim_id=<claim_id> : delete by file claim id
--outpoint=<outpoint> : delete by file claim outpoint
--rowid=<rowid> : delete by file row id
--name=<name> : delete by associated name claim of file
2017-06-09 18:14:03 +02:00
Returns:
(bool) true if deletion was successful
```
## file_list
```text
List files limited by optional filters
Usage:
file_list [--sd_hash=<sd_hash>] [--file_name=<file_name>] [--stream_hash=<stream_hash>]
[--claim_id=<claim_id>] [--outpoint=<outpoint>] [--rowid=<rowid>]
[--name=<name>]
[-f]
Options:
--sd_hash=<sd_hash> : get file with matching sd hash
--file_name=<file_name> : get file with matching file name in the
downloads folder
--stream_hash=<stream_hash> : get file with matching stream hash
--claim_id=<claim_id> : get file with matching claim id
--outpoint=<outpoint> : get file with matching claim outpoint
--rowid=<rowid> : get file with matching row id
--name=<name> : get file with matching associated name claim
-f : full status, populate the 'message' and 'size' fields
Returns:
(list) List of files
[
{
'completed': (bool) true if download is completed,
'file_name': (str) name of file,
'download_directory': (str) download directory,
'points_paid': (float) credit paid to download file,
'stopped': (bool) true if download is stopped,
'stream_hash': (str) stream hash of file,
'stream_name': (str) stream name ,
'suggested_file_name': (str) suggested file name,
'sd_hash': (str) sd hash of file,
'name': (str) name claim attached to file
'outpoint': (str) claim outpoint attached to file
'claim_id': (str) claim ID attached to file,
'download_path': (str) download path of file,
'mime_type': (str) mime type of file,
'key': (str) key attached to file,
'total_bytes': (int) file size in bytes, None if full_status is false
'written_bytes': (int) written size in bytes
'message': (str), None if full_status is false
'metadata': (dict) Metadata dictionary
},
]
```
## file_set_status
```text
Start or stop downloading a file
Usage:
file_set_status <status> [--sd_hash=<sd_hash>] [--file_name=<file_name>]
[--stream_hash=<stream_hash>] [--claim_id=<claim_id>]
[--outpoint=<outpoint>] [--rowid=<rowid>]
[--name=<name>]
Options:
--sd_hash=<sd_hash> : set status of file with matching sd hash
--file_name=<file_name> : set status of file with matching file name in the
downloads folder
--stream_hash=<stream_hash> : set status of file with matching stream hash
--claim_id=<claim_id> : set status of file with matching claim id
--outpoint=<outpoint> : set status of file with matching claim outpoint
--rowid=<rowid> : set status of file with matching row id
--name=<name> : set status of file with matching associated name claim
Returns:
(str) Confirmation message
```
## get
```text
Download stream from a LBRY name.
Usage:
get <uri> [<file_name> | --file_name=<file_name>] [<timeout> | --timeout=<timeout>]
[<download_directory> | --download_directory=<download_directory>]
Options:
<file_name> : specified name for the downloaded file
<timeout> : download timeout in number of seconds
<download_directory> : path to directory where file will be saved
Returns:
(dict) Dictionary contaning information about the stream
{
'completed': (bool) true if download is completed,
'file_name': (str) name of file,
'download_directory': (str) download directory,
'points_paid': (float) credit paid to download file,
'stopped': (bool) true if download is stopped,
'stream_hash': (str) stream hash of file,
'stream_name': (str) stream name,
'suggested_file_name': (str) suggested file name,
'sd_hash': (str) sd hash of file,
'name': (str) name claim attached to file
'outpoint': (str) claim outpoint attached to file
'claim_id': (str) claim ID attached to file,
'download_path': (str) download path of file,
'mime_type': (str) mime type of file,
'key': (str) key attached to file,
'total_bytes': (int) file size in bytes, None if full_status is false
'written_bytes': (int) written size in bytes
'message': (str), None if full_status is false
'metadata': (dict) Metadata dictionary
}
```
## get_availability
```text
Get stream availability for lbry uri
Usage:
get_availability (<uri> | --uri=<uri>) [<sd_timeout> | --sd_timeout=<sd_timeout>]
[<peer_timeout> | --peer_timeout=<peer_timeout>]
Options:
<sd_timeout>, --sd_timeout=<sd_timeout> : sd blob download timeout
<peer_timeout>, --peer_timeout=<peer_timeout> : how long to look for peers
Returns:
(float) Peers per blob / total blobs
```
## help
```text
Return a useful message for an API command
Usage:
help [<command> | --command=<command>]
Options:
<command>, --command=<command> : command to retrieve documentation for
```
## peer_list
```text
Get peers for blob hash
Usage:
peer_list (<blob_hash> | --blob_hash=<blob_hash>) [<timeout> | --timeout=<timeout>]
Options:
<timeout>, --timeout=<timeout> : peer search timeout in seconds
Returns:
(list) List of contacts
```
## publish
```text
Make a new name claim and publish associated data to lbrynet,
update over existing claim if user already has a claim for name.
Fields required in the final Metadata are:
'title'
'description'
'author'
'language'
'license'
'nsfw'
Metadata can be set by either using the metadata argument or by setting individual arguments
fee, title, description, author, language, license, license_url, thumbnail, preview, nsfw,
or sources. Individual arguments will overwrite the fields specified in metadata argument.
Usage:
publish (<name> | --name=<name>) (<bid> | --bid=<bid>) [--metadata=<metadata>]
[--file_path=<file_path>] [--fee=<fee>] [--title=<title>]
[--description=<description>] [--author=<author>] [--language=<language>]
[--license=<license>] [--license_url=<license_url>] [--thumbnail=<thumbnail>]
[--preview=<preview>] [--nsfw=<nsfw>] [--sources=<sources>]
[--channel_name=<channel_name>] [--channel_id=<channel_id>]
2017-06-16 01:55:44 +02:00
[--claim_address=<claim_address>] [--change_address=<change_address>]
2017-06-09 18:14:03 +02:00
Options:
--metadata=<metadata> : ClaimDict to associate with the claim.
--file_path=<file_path> : path to file to be associated with name. If provided,
a lbry stream of this file will be used in 'sources'.
If no path is given but a metadata dict is provided,
the source from the given metadata will be used.
--fee=<fee> : Dictionary representing key fee to download content:
{
'currency': currency_symbol,
'amount': float,
'address': str, optional
}
supported currencies: LBC, USD, BTC
If an address is not provided a new one will be
automatically generated. Default fee is zero.
--title=<title> : title of the publication
--description=<description> : description of the publication
--author=<author> : author of the publication
--language=<language> : language of the publication
--license=<license> : publication license
--license_url=<license_url> : publication license url
--thumbnail=<thumbnail> : thumbnail url
--preview=<preview> : preview url
--nsfw=<nsfw> : title of the publication
--sources=<sources> : {'lbry_sd_hash':sd_hash} specifies sd hash of file
--channel_name=<channel_name> : name of the publisher channel name in the wallet
--channel_id=<channel_id> : claim id of the publisher channel, does not check
for channel claim being in the wallet. This allows
publishing to a channel where only the certificate
private key is in the wallet.
--claim_address=<claim_address> : address where the claim is sent to, if not specified
new address wil automatically be created
Returns:
(dict) Dictionary containing result of the claim
{
'tx' : (str) hex encoded transaction
'txid' : (str) txid of resulting claim
'nout' : (int) nout of the resulting claim
'fee' : (float) fee paid for the claim transaction
'claim_id' : (str) claim ID of the resulting claim
}
```
## reflect
```text
Reflect a stream
Usage:
reflect (<sd_hash> | --sd_hash=<sd_hash>)
Returns:
(bool) true if successful
```
## report_bug
```text
Report a bug to slack
Usage:
report_bug (<message> | --message=<message>)
Returns:
(bool) true if successful
```
## resolve
```text
2017-06-16 01:55:44 +02:00
Resolve given LBRY URIs
2017-06-09 18:14:03 +02:00
Usage:
2017-06-16 01:55:44 +02:00
resolve [-f] (<uri> | --uri=<uri>) [<uris>...]
2017-06-09 18:14:03 +02:00
Options:
-f : force refresh and ignore cache
Returns:
2017-06-16 01:55:44 +02:00
Dictionary of results, keyed by uri
'<uri>': {
If a resolution error occurs:
'error': Error message
If the uri resolves to a channel or a claim in a channel:
'certificate': {
2017-06-09 18:14:03 +02:00
'address': (str) claim address,
'amount': (float) claim amount,
'effective_amount': (float) claim amount including supports,
'claim_id': (str) claim id,
'claim_sequence': (int) claim sequence number,
'decoded_claim': (bool) whether or not the claim value was decoded,
'height': (int) claim height,
'depth': (int) claim depth,
'has_signature': (bool) included if decoded_claim
'name': (str) claim name,
'supports: (list) list of supports [{'txid': txid,
'nout': nout,
'amount': amount}],
'txid': (str) claim txid,
'nout': (str) claim nout,
'signature_is_valid': (bool), included if has_signature,
'value': ClaimDict if decoded, otherwise hex string
}
2017-06-16 01:55:44 +02:00
If the uri resolves to a claim:
'claim': {
'address': (str) claim address,
'amount': (float) claim amount,
'effective_amount': (float) claim amount including supports,
'claim_id': (str) claim id,
'claim_sequence': (int) claim sequence number,
'decoded_claim': (bool) whether or not the claim value was decoded,
'height': (int) claim height,
'depth': (int) claim depth,
'has_signature': (bool) included if decoded_claim
'name': (str) claim name,
'channel_name': (str) channel name if claim is in a channel
'supports: (list) list of supports [{'txid': txid,
'nout': nout,
'amount': amount}]
'txid': (str) claim txid,
'nout': (str) claim nout,
'signature_is_valid': (bool), included if has_signature,
'value': ClaimDict if decoded, otherwise hex string
}
2017-06-09 18:14:03 +02:00
}
```
## resolve_name
```text
Resolve stream info from a LBRY name
Usage:
resolve_name <name> [-f]
Options:
-f : force refresh and do not check cache
Returns:
(dict) Metadata dictionary from name claim, None if the name is not
resolvable
```
## send_amount_to_address
```text
Queue a payment of credits to an address
Usage:
send_amount_to_address (<amount> | --amount=<amount>) (<address> | --address=<address>)
Returns:
(bool) true if payment successfully scheduled
```
## settings_get
```text
Get daemon settings
Usage:
settings_get
Returns:
(dict) Dictionary of daemon settings
See ADJUSTABLE_SETTINGS in lbrynet/conf.py for full list of settings
```
## settings_set
```text
Set daemon settings
Args:
'run_on_startup': (bool) currently not supported
'data_rate': (float) data rate,
'max_key_fee': (float) maximum key fee,
'disable_max_key_fee': (bool) true to disable max_key_fee check,
2017-06-09 18:14:03 +02:00
'download_directory': (str) path of where files are downloaded,
'peer_port': (int) port through which daemon should connect,
2017-06-09 18:14:03 +02:00
'max_upload': (float), currently not supported
'max_download': (float), currently not supported
'download_timeout': (int) download timeout in seconds
'search_timeout': (float) search timeout in seconds
'cache_time': (int) cache timeout in seconds
Returns:
(dict) Updated dictionary of daemon settings
```
## status
```text
Get daemon status
Usage:
status [-s] [-d]
Options:
-s : include session status in results
-d : include dht network and peer status
2017-06-16 01:55:44 +02:00
Returns:
(dict) lbrynet-daemon status
{
'lbry_id': lbry peer id, base58
'installation_id': installation id, base58
'is_running': bool
'is_first_run': bool
'startup_status': {
'code': status code
'message': status message
},
'connection_status': {
'code': connection status code
'message': connection status message
},
'blockchain_status': {
'blocks': local blockchain height,
'blocks_behind': remote_height - local_height,
'best_blockhash': block hash of most recent block,
},
If given the session status option:
'session_status': {
'managed_blobs': count of blobs in the blob manager,
'managed_streams': count of streams in the file manager
}
If given the dht status option:
'dht_status': {
'kbps_received': current kbps receiving,
'kbps_sent': current kdps being sent,
'total_bytes_sent': total bytes sent
'total_bytes_received': total bytes received
'queries_received': number of queries received per second
'queries_sent': number of queries sent per second
'recent_contacts': count of recently contacted peers
'unique_contacts': count of unique peers
}
}
2017-06-09 18:14:03 +02:00
```
## stream_cost_estimate
```text
Get estimated cost for a lbry stream
Usage:
stream_cost_estimate <uri> [<size> | --size=<size>]
Options:
<size>, --size=<size> : stream size in bytes. if provided an sd blob won't be
downloaded.
Returns:
(float) Estimated cost in lbry credits, returns None if uri is not
resolveable
```
## transaction_list
```text
List transactions belonging to wallet
Usage:
transaction_list
Returns:
(list) List of transactions
```
## transaction_show
```text
Get a decoded transaction from a txid
Usage:
transaction_show (<txid> | --txid=<txid>)
Returns:
(dict) JSON formatted transaction
```
## version
```text
Get lbry version information
Usage:
version
Returns:
(dict) Dictionary of lbry version information
{
'build': (str) build type (e.g. "dev", "rc", "release"),
'ip': (str) remote ip, if available,
'lbrynet_version': (str) lbrynet_version,
'lbryum_version': (str) lbryum_version,
'lbryschema_version': (str) lbryschema_version,
'os_release': (str) os release string
'os_system': (str) os name
'platform': (str) platform string
'processor': (str) processor type,
'python_version': (str) python version,
}
```
## wallet_balance
```text
Return the balance of the wallet
Usage:
wallet_balance [<address> | --address=<address>] [-u]
Options:
<address> : If provided only the balance for this address will be given
-u : Include unconfirmed
Returns:
(float) amount of lbry credits in wallet
```
## wallet_is_address_mine
```text
Checks if an address is associated with the current wallet.
Usage:
wallet_is_address_mine (<address> | --address=<address>)
Returns:
(bool) true, if address is associated with current wallet
```
## wallet_list
```text
List wallet addresses
Usage:
wallet_list
Returns:
List of wallet addresses
```
## wallet_new_address
```text
Generate a new wallet address
Usage:
wallet_new_address
Returns:
(str) New wallet address in base58
```
## wallet_public_key
```text
Get public key from wallet address
Usage:
wallet_public_key (<address> | --address=<address>)
Returns:
(list) list of public keys associated with address.
Could contain more than one public key if multisig.
```
## wallet_unused_address
```text
Return an address containing no balance, will create
a new address if there is none.
Usage:
wallet_unused_address
Returns:
(str) Unused wallet address in base58
```