Guides

The CLI "bit"

Suggest Edits

bit, the bit.io Command Line Tool

The bit command line tool is installed when you install the python library. The easiest way to do this is with:

pip install bitdotio

If you run into any trouble, see the https://docs.bit.io/docs/using-python-bitdotio

The tool is installed alongside your python binary, so be sure that is in your PATH.

You'll want to grab your API key from your bit.io account - to get the key, log into to bit.io and
click on the green "Connect" button, and copy the API key.

To run the tool, just type bit

Usage: bit [OPTIONS] COMMAND [ARGS]...

Options:
  -k, --key TEXT  Your bit.io API key, available when you click the connect
                  button in bit.io  [required]

  -v, --verbose   Verbose output  [default: False]
  --help          Show this message and exit.

Commands:
  import
  query
  repo

All of the commands return JSON.

Note that while the examples below use the key on the command line, you can set the key via the environment variable
BITIO_KEY (this keeps the key from showing up in, eg, a ps command, and allows secret injection for systems like Kubernetes):

BITIO_KEY=<your key> bit repo list

This is the same as:

bit -k <your_key> repo list

Alternatively, you can use export BITIO_KEY=<your_bitio_key> to make the API key accessible to future bit calls without needing the -k argument.

Importing Data

With the command line tool you can upload data from a file, from a url, or just use JSON directly. All
the importing commands (aside from status) take an optional table_name to indicate the destination table name;
if that table doesn't exist the import will create it. If you don't provide a table_name bit.io creates a table
based on the filename.

To create a repo to import data into, see https://docs.bit.io/docs/using-bit-the-command-line-tool#create-a-repo.

Importing from a file

bit -k <your_key> import file -r my_new_repo -f foo.csv -t from_file

You'll get:

{
    "result": "success",
    "message": "Uploaded file addresses.csv saved successfully from sender [email protected] and an ingestion job has been created with the status RECEIVED",
    "table_name": "from_file",
    "repo_name": "my_new_repo",
    "job_id": "34a0539f-39f8-483c-84b5-c858c7d26e10",
    "file_name": "addresses.csv"
}

You can use that job_id in the status command.

You can also pipe your file in; if you do this, you must provide the table_name option:

cat foo.csv | bit -k <your_key> import file -r my_new_repo -f - --table_name foo_table

And you'll get:

{
    "result": "success",
    "message": "Uploaded file <stdin> saved successfully from sender [email protected] and an ingestion job has been created with the status RECEIVED",
    "table_name": "foo_table",
    "repo_name": "my_new_repo",
    "job_id": "c9a551b2-3149-4439-9527-952e7a3fe23",
    "file_name": "<stdin>"
}

Import status

bit -k <your_key> import status -i 34a0539f-39f8-483c-84b5-c858c7d26e10

And you'd get:

{
    "job_id": "34a0539f-39f8-483c-84b5-c858c7d26e10",
    "state": "DONE",
    "status_message": "",
    "retries": 0,
    "file_type": null,
    "original_filename": "addresses.csv",
    "repo_name": "my_new_repo",
    "table_name": "from_file"
}

Import from url

bit -k <your_key> import url -r my_new_repo -u https://storage.googleapis.com/bitdotio-demo-datasets/atl_2020_home_sales.csv

And you'll get:

{
    "result": "success",
    "message": "https://storage.googleapis.com/bitdotio-demo-datasets/atl_2020_home_sales.csv queued for processing successfully, and an ingestion job has been created with the status RECEIVED",
    "table_name": "atl_2020_home_sales.csv",
    "repo_name": "my_new_repo",
    "job_id": "a837e2ed-2bd2-44ae-a3f0-e18f52274061",
    "file_name": "atl_2020_home_sales.csv",
    "url": "https://storage.googleapis.com/bitdotio-demo-datasets/atl_2020_home_sales.csv"
}

Import JSON

echo "[[1,2], [3,4]]" | bit -k <your_key> import json-data -r my_new_repo -t json_test

And you'll get:

{
    "result": "success",
    "message": "Uploaded file adam_e6d3aaf4-0469-4bf7-a06a-eb6683c1e563.json saved successfully from sender [email protected] and an ingestion job has been created with the status RECEIVED",
    "table_name": "json_test",
    "repo_name": "my_new_repo",
    "job_id": "436d0335-184c-42f1-98b3-d24be2ef7701",
    "file_name": "adam_e6d3aaf4-0469-4bf7-a06a-eb6683c1e563.json"
}

Querying data

You can also query your data with the command line tool:

bit -k <your_key> query -q "SELECT *  FROM \"a/demo_repo\".\"atl_home_sales\""

Or from stdin:

echo  "SELECT *  FROM \"a/demo_repo\".\"atl_home_sales\"" | bit -k <your_key> query -qf -

Repo Management

List repos

bit -k <your_key> repo list

You'll get something like:

[
    {
        "name": "demo_repo",
        "description": "",
        "documentation": "",
        "bytes": 622592,
        "is_private": true
    },
    {
        "name": "my_new_repo",
        "description": "",
        "documentation": "",
        "bytes": 13099008,
        "is_private": true
    },
    {
        "name": "my-repo",
        "description": "my-repo",
        "documentation": "",
        "bytes": 16384,
        "is_private": true
    },
    {
        "name": "power-usage",
        "description": "",
        "documentation": "",
        "bytes": 16384,
        "is_private": true
    }
]

Create a repo

bit -k <your_key> repo create -r my_new_repo

And you'll get:

{
    "name": "my_new_repo",
    "description": "",
    "documentation": "",
    "bytes": 0,
    "is_private": true
}

Get a specific repo's information

bit -k <your_key> repo retrieve -r my_new_repo

And you'll get:

{
    "name": "my_new_repo",
    "description": "",
    "documentation": "",
    "bytes": 0,
    "is_private": true
}

If you have any question please reach out to [email protected] and we'll help you out!

Updated 11 months ago

Did this page help you?