The 21 Command Line Interface

Posted by Veerbhan Kheterpal, Balaji Srinivasan

21 Command Line Interface

The 21 command line interface provides a convenient interface to all of 21's essential functions. Some of the key features that it supports are:

  1. Setting up your 21 account.
  2. Setting up a Bitcoin wallet.
  3. Allowing to sell and earn bitcoins

Verifying the installation of 21 CLI

To verify that the CLI is properly installed, use the 21 --version command.

[twenty@bitcoin:~]$ 21 --version
21 v2.3.6

You should see 21 vA.B.C in the output. If not, then your installation of the 21 Command Line is corrupted. Please refer to the setup instructions for further instructions on how to reinstall 21.

Obtaining inline documentation on the CLI

You can obtain documentation on the set of commands that the CLI offers by using the 21 help command or the 21 --help command switch.

[twenty@bitcoin:~]$ 21 help
Usage: 21 [OPTIONS] COMMAND [ARGS]...

  Buy and sell anything on the internet for bitcoin.

  For detailed help, run 21 help --detail.
  For full documentation, visit 21.co/learn.

Options:
  --config-file PATH  Path to config (default: /home/user/.two1/two1.json)
  --config KEY VALUE  Overrides a config key/value pair.
  --version           Show the version and exit.
  -h, --help          Show this message and exit.

Commands:
  buy         Buy API calls with bitcoin.
  buybitcoin  Buy bitcoin through Coinbase.
  doctor      Diagnose this 21 installation.
  earn        Earn bitcoin by doing microtasks.
  flush       Flush your 21.co buffer to the blockchain.
  help        Show help and exit.
  inbox       View notifications from 21.co.
  join        Join a p2p network to buy/sell for BTC.
  log         View a log of events of earning/spending BTC.
  login       Login to your 21.co account.
  mine        Mine bitcoin at the command line.
  profile     Open your 21.co profile in a web browser.
  publish     Publish apps to the 21 Marketplace.
  rate        Rate an app listed in the 21 Marketplace.
  search      Search for apps listed on the 21 Marketplace.
  sell        Start local server to sell APIs for bitcoin.
  send        Send a specified address some satoshis.
  status      View your bitcoin balance and address.
  uninstall   Uninstall 21 and its dependencies.
  update      Update the 21 Command Line Interface.

Further documentation on each command can be obtained by invoking --help on the command itself. For example, contextual help on the buy command can be obtained using 21 buy --help command.

Setting up a 21 account

In order to use most commands, you will need to set up a 21 account. After you have done that, you can login using the 21 login command.

[twenty@bitcoin:~]$ 21 login
You do not have a Bitcoin wallet configured. Let's create one. Press any key ...

Wallet successfully created.

You can recover the private key to your wallet using the following 12 words (in this order) :

champion hotel review lake toaster immense picnic soldier glimpse candy girl side

Write down and store these words in a safe place.

Press any key ...

If you don't have a 21 account, visit https://21.co/signup to create one. 

Username: harding4
Password (Typing will be hidden): 
logging in harding4
Setting default payout address to: 115kjVQznK4Skp8z9TYKanWgLU5oQXS1Bp
Check out our introductory guide to learn the basics of 21: https://21.co/learn/intro-to-21/

As you can see, you were prompted to create a wallet. It's very important that you save the 12 words you were provided, as you will need them to recover your bitcoins if you lose your computer or your hard drive crashes. The technology behind Bitcoin makes it impossible for us to recover your wallet for you, so you must backup those 12 words.

You are also prompted for your username and password, which are the same as you used when you created an account on the signup page.

You may also connect a social media account to receive an initial balance or learn to use 21 sell to earn additonal income you can use to complete some of the steps in this tutorial.

Checking the status of your 21 account

The CLI provides a 21 status command to display a range of information across several categories:

[twenty@bitcoin:~]$ 21 status

Let's take a look at the different sections that are displayed by the 21 status command.

21.co account

This secion displays your Username.

Logged in as: heybitcoin

Mining

If you have a 21 Bitcoin computer, the status of the 21 Bitcoin Chip is reported along with the current Hashrate. You might see (warming up) if the chip has been running for less than 15 minutes. Further, the total number of satoshis that your Bitcoin Chip has mined is also displayed.

Mining
        Status           : 21 mining chip running (/run/minerd.pid)
        Hashrate         : ~50 GH/s (warming up)
        Mined (all time) : 55 Satoshis

Type 21 mine --dashboard to see a detailed view. Hit q to exit.

Balance

Your bitcoin balance is shown across the following three entries:

  1. 21.co Account Buffer These are the bitcoin earnings in your 21.co account.
  2. Blockchain Balance This is the amount of Bitcoin you have on the blockchain (in your wallet). You can run the 21 status --detail command to get the breakdown of this balance along with your list of Bitcoin addresses.
  3. Being transferred: The amount of bitcoin that is being transferred from your 21.co account to your wallet on the blockchain.
Total Balance
    Your spendable buffer at 21.co [1]                        : 76937 satoshis
    Your spendable balance on the Blockchain [2]              : 1663863 satoshis
    Your spendable balance in Payment Channels                : 95000 satoshis
    Amount flushing from 21.co buffer to Blockchain balance   : 0 satoshis

    [1]: Available for off-chain transactions
    [2]: Available for on-chain and payment channel transactions
    (See 21.co/micropayments for more details)

    To see all wallet addresses and open payment channels, use '21 status --detail'

Use 21 buy to buy API calls for bitcoin from 21.co.
For help, do 21 buy --help.

Bitcoin-payable API demos

21 has hosted a set of Bitcoin-payable API demo endpoints on mkt.21.co. These APIs can be directly purchased from the command line using the 21 buy command. The 21 buy --help command to list the set of available APIs.

[twenty@bitcoin:~]$ 21 buy --help
Usage: 21 buy [OPTIONS] RESOURCE...

  Buy API calls with bitcoin.

  Usage
  -----
  Buy a bitcoin-payable resource.
  $ 21 buy <resource>

  Get state, city, latitude, longitude, and estimated population for a given zip code.
  $ 21 buy "https://mkt.21.co/21dotco/zip_code_data/zipdata/collect?zip_code=94109" --maxprice 2750

Options:
  -i, --info                      Retrieve initial 402 payment information.
  -p, --payment-method [offchain|onchain|channel]
  -H, --header TEXT               HTTP header to include with the request
  -X, --request TEXT              HTTP request method
  -o, --output TEXT               Output file
  -d, --data TEXT                 Data to send in HTTP body
  --data-file FILENAME            Data file to send in HTTP body
  --maxprice INTEGER              Maximum amount to pay
  -h, --help                      Show this message and exit.

Demo: Pay bitcoin to get location data

This demo implements very simple functionality where you can pay bitcoin to buy data about a particular location based on its zip code. Make sure that you have enough buffer in your 21.co Account by using the 21 status command.

[twenty@bitcoin:~]$  21 buy "https://mkt.21.co/21dotco/zip_code_data/zipdata/collect?zip_code=94109" --maxprice 2750
{
    "City": "SAN FRANCISCO",
    "Decommisioned": "false",
    "EstimatedPopulation": "38763",
    "Lat": "37.79",
    "Long": "-122.42",
    "State": "CA",
    "Zipcode": "94109",
    "ZipcodeType": "STANDARD"
}

Flushing bitcoins from your 21.co account to the blockchain

CLI commands such as buy work with your 21 account buffer. The 21 account buffer represents the sum of all received and sent bitcoins. In order to flush your buffer in the 21.co account to the blockchain, use the 21 flush command.

[twenty@bitcoin:~]$ 21 flush
Flush to Blockchain
Your mined Satoshis will be sent to you on the Blockchain in the next payout cycle.
Estimated time of payout: ~20 minutes.
To check progress:  https://blockchain.info/address/187VM4pdZzhch8w5wo436cbG5RhYFdLAtg
To get more bitcoin, use 21 sell.

The command provides a link to the blockchain record for the receiving Bitcoin address. The flush operation usually takes about 10 to 20 minutes to complete. You should be able to see your updated blockchain balance by running the 21 status command.

Checking the activity on your 21 account

All the 21 CLI commands that you have perfomed so far either affect your 21 account buffer or your blockchain balance. The 21 log command provides a detailed record of all balance related activities on your 21 account.

The records are shown in descending order (newest first).

  1. Received 40,000 satoshis for mining on the Bitcoin Computer
  2. Spent 2,750 satoshis for zipcode data
[twenty@bitcoin:~]$ 21 log
21 Bitcoin Computer Activity Log.

2016-04-07 10:24:38 UTC-07:00 : -2750 Satoshis from your 21.co buffer
Description: You bought https://mkt.21.co/21dotco/zip_code_data/zipdata/collect?zip_code=94109 from 21dotco


2016-04-07 10:24:10 UTC-07:00 : +40000 Satoshis to your 21.co buffer
Description: You just received a little bit of bitcoin.

Joining the 21 Peer-to-Peer Network

You can join the 21 peer-to-peer network (and virtual private marketplace) with the following command:

21 market join

Updating the 21 Command Line using the CLI

We are constantly adding new features. The 21 update command checks for a new release of the 21 Command Line and performs a software update.

[twenty@bitcoin:~]$ 21 update
Checking for application updates...