About
Protocol
Walkthroughs
Integrations
Intro to NFT Metadata
Tutorials
Smart Contracts
Concepts
Playbooks
Learn
CLI
Experiment with creating, editing, and querying tables from the comfort of the command line.
The @tableland/cli
is a developer tool to help you connect, create, write, and read from The comfort of your command line. It’s simple, easy to use, and integrates nicely with tools like jq. When interacting with the Tableland CLI, you can also specify your own provider endpoints for added control. Using the CLI, you can:
- Connect to any of the chains that Tableland supports
- Create, write to, and read from tables
- Retrieve and set table controllers
- Leverage utility commands for retrieving other table related information
Setup
Install
You can install the CLI tool via npm
:
npm install -g @tableland/cli@latest
Or yarn
:
yarn global add @tableland/cli@latest
Usage patterns
Most of the common Tableland usage patterns are possible via the command line. In general, you'll need to connect (to a host/provider), create a table (with a schema, using create
), insert/mutate values (write
), and query (read
) a table. Developers can even retrieve all tables owned by a specific EVM address (using list
). And for a full list of valid SQL statements used throughout these different commands, check out the SQL Specification’s statement types.
There also exists some useful commands for on-chain information. View Tableland’s live chain deployments & smart contract addresses (chains
) or retrieve on-chain data from a create
or write
query (passing the transaction hash to receipt
). Lastly, the corresponding token metadata about a table can also be requested (i.e., tables are on-chain as ERC721s — the minted table’s name can be passed to info
).
Examples format
All examples use the chain local-tableland
. For many of the examples, the format <some_text_here>
will be used to denote a value passed the developer. For example, in --private-key <private_key>
, some private key abc123
would then be used as --private-key abc123
.
Additionally, a table created with the prefix cli_demo_table
should resemble something like cli_demo_table_31337_2
, where 31337
is the specific chain and 2
is unique to the chain / table owner. This is the standard {prefix}_{chainId}_{tableId}
format. Be sure to replace prefix
, chainId
, & tableId
with your unique values.
Commands
There are a number of commands available for interacting with Tableland. Each one has a specific set of required and optional arguments, plus various flags.
tableland <command> <arguments> [flags]
Synopsis
tableland chains
List information about supported chains.
tableland controller <subcommand>
(string)
Get, set, and lock the controller contract for a given table.
subcommand
valuesget <name>
(string)
Get the current controller address for a table.
set <controller> <name>
(string; string)
Set the controller address for a table.
lock <name>
(string)
Lock the controller address for a table.
tableland create <schema> [prefix]
(string; string)
Create a new table (prefix is optional).
tableland info <name>
(string)
Get info about a given table by name.
tableland init
Create a config file.
tableland list <address>
(string)
List tables by address.
tableland read <statement>
(string)
Run a read-only query against a remote table.
tableland receipt <hash>
(string)
Get the receipt of a chain transaction to know if it was executed, and the execution details.
tableland schema <name>
(string)
Get info about a given table schema.
tableland write <statement>
(string)
Run a mutating SQL statement against a remote table.
tableland shell [statement]
(string)
Interact with tableland via an interactive shell environment.
Global Flags
The Tableland CLI includes a number of global flags.
--help
Show help.
--version
Show version number.
-k, --privateKey <private_key>
(string)
Private key string.
Note: most commands, aside from read queries, will need to flag a --privateKey
(or set the configuration variables with the init
command).
-c, --chain <chain_name>
(string)
The EVM chain to target (default: maticmum
).
chain_name
valuesTestnets
goerli
(Ethereum Goerli)maticmum
(Polygon Mumbai)optimism-goerli
arbitrum-goerli
Mainnets
mainnet
(Ethereum)homestead
(Ethereum)matic
(Polygon)optimism
arbitrum
Local
localhost
local-tableland
--baseUrl <url>
(string)
The URL of a Tableland validator.
--providerUrl <url>
(string)
JSON RPC API provider URL (e.g., https://eth-rinkeby.alchemyapi.io/v2/123abc123a...
).
Defaults
The following are the default options:
--chain
⇒maticmum
Polygon Mumbai has been set as the default chain; any other chain names from thetableland chains
command can be used.
init
tableland init
Create a config file.
Before starting with the CLI, it’s best to create a config file. This will create a JSON or YAML file that stores a privateKey
, chain
, and providerUrl
. Once these are set, commands will leverage these values.
Run the command, and then follow the prompts:
tableland init
This will trigger a series of steps. First, select your desired chain:
? Select a preferred default chain (Use arrow keys)
❯ mainnet
homestead
optimism
arbitrum
matic
goerli
optimism-goerli
arbitrum-goerli
maticmum
localhost
local-tableland
You’ll want to set your private key. For example, a private key with value 59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d
is an openly used account the comes with local node tooling like Hardhat, so it can also be used if you’re developing with local-tablealand
. However, for any mainnets or testnets, it’s best to use your own private key.
? Enter your private key (optional)
59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d
Set your preferred format (JSON or YAML):
? Select a config file output format
❯ json
yaml
Store your provider URL (Alchemy, Infura, etc.):
? Enter a default JSON RPC API provider URL (optional)
https://eth-mainnet.alchemyapi.io/v2/123abc123a...
Then, enter the path where this value should be stored; the default value will be under /Users/$USER/.tablelandrc.json
:
? Enter path to store config file (use "." to print to stdout)
(/Users/$USER/.tablelandrc.json)
The resulting config file will resemble the following:
{
"privateKey": "59c6995e998f97a5a0044966f0945389dc9e86dae88c7a8412f4603b6b78690d",
"chain": "mainnet",
"providerUrl": "https://eth-mainnet.alchemyapi.io/v2/123abc123a..."
}
chains
tableland chains
List information about supported chains.
In particular, use the chains
command to retrieve which chains Tableland is deployed on, which returns information about the deployment itself, including the chain name, id, and contract address:
Example
tableland chains
{
mainnet: {
chainName: 'mainnet',
chainId: 1,
contractAddress: '0x012969f7e3439a9B04025b5a049EB9BAD82A8C12',
baseUrl: 'https://tableland.network/api/v1'
},
homestead: {
chainName: 'homestead',
chainId: 1,
contractAddress: '0x012969f7e3439a9B04025b5a049EB9BAD82A8C12',
baseUrl: 'https://tableland.network/api/v1'
},
optimism: {
chainName: 'optimism',
chainId: 10,
contractAddress: '0xfad44BF5B843dE943a09D4f3E84949A11d3aa3e6',
baseUrl: 'https://tableland.network/api/v1'
},
arbitrum: {
chainName: 'arbitrum',
chainId: 42161,
contractAddress: '0x9aBd75E8640871A5a20d3B4eE6330a04c962aFfd',
baseUrl: 'https://tableland.network/api/v1'
},
matic: {
chainName: 'matic',
chainId: 137,
contractAddress: '0x5c4e6A9e5C1e1BF445A062006faF19EA6c49aFeA',
baseUrl: 'https://tableland.network/api/v1'
},
goerli: {
chainName: 'goerli',
chainId: 5,
contractAddress: '0xDA8EA22d092307874f30A1F277D1388dca0BA97a',
baseUrl: 'https://testnets.tableland.network/api/v1'
},
'optimism-goerli': {
chainName: 'optimism-goerli',
chainId: 420,
contractAddress: '0xC72E8a7Be04f2469f8C2dB3F1BdF69A7D516aBbA',
baseUrl: 'https://testnets.tableland.network/api/v1'
},
'arbitrum-goerli': {
chainName: 'arbitrum-goerli',
chainId: 421613,
contractAddress: '0x033f69e8d119205089Ab15D340F5b797732f646b',
baseUrl: 'https://testnets.tableland.network/api/v1'
},
maticmum: {
chainName: 'maticmum',
chainId: 80001,
contractAddress: '0x4b48841d4b32C4650E4ABc117A03FE8B51f38F68',
baseUrl: 'https://testnets.tableland.network/api/v1'
},
localhost: {
chainName: 'localhost',
chainId: 31337,
contractAddress: '',
baseUrl: 'http://localhost:8080/api/v1'
},
'local-tableland': {
chainName: 'local-tableland',
chainId: 31337,
contractAddress: '0xe7f1725e7734ce288f8367e1bb143e90bb3f0512',
baseUrl: 'http://localhost:8080/api/v1'
}
}
controller
tableland controller <subcommand>
Get, set, and lock the controller contract for a given table.
Use these commands as a helper to retrieve the controller of a table (get
) or to set or permanently lock the controller of a table (set
or lock
). Recall the name
is in the format {prefix}_{chainId}_{tableId}
.
Subcommands
get <name>
(string)
Get the current controller address for a table.
set <controller> <name>
(string [string])
Set the controller address for a table.
lock <name>
(string)
Lock the controller address for a table.
Example
get
tableland controller get cli_demo_table_31337_2
"0x0000000000000000000000000000000000000000"
Note: this example table originally had its controller set as 0x0
, which is the default value.
set
tableland controller set 0x3C44CdDdB6a900fa2b585dd299e03d12FA4293BC cli_demo_table_31337_2
{
type: 2,
chainId: 31337,
nonce: 3,
maxPriorityFeePerGas: BigNumber { _hex: '0x59682f00', _isBigNumber: true },
maxFeePerGas: BigNumber { _hex: '0x59682f0e', _isBigNumber: true },
gasPrice: null,
gasLimit: BigNumber { _hex: '0xf14a', _isBigNumber: true },
to: '0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512',
value: BigNumber { _hex: '0x00', _isBigNumber: true },
data: '0x8bb0ab9700000000000000000000000070997970c51812dc3a010c7d01b50e0d17dc79c800000000000000000000000000000000000000000000000000000000000000020000000000000000000000003c44cdddb6a900fa2b585dd299e03d12fa4293bc',
accessList: [],
hash: '0x5f8d81e07b908e501a8ccc1257bf2691400f3c68b657af3b36fa21fec0d9b16b',
v: 1,
r: '0x1e0ad1b9fc72c9d909ec64dd89d888e9299f5f2f57968d06fd737389357a5634',
s: '0x429cdb090c318e50d3197cbb7405651b7c330dda15af2c4256ba47ae80deffcb',
from: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8',
confirmations: 0,
wait: [Function (anonymous)],
link: ''
}
lock
tableland controller lock cli_demo_table_31337_2
{
type: 2,
chainId: 31337,
nonce: 4,
maxPriorityFeePerGas: BigNumber { _hex: '0x59682f00', _isBigNumber: true },
maxFeePerGas: BigNumber { _hex: '0x59682f0e', _isBigNumber: true },
gasPrice: null,
gasLimit: BigNumber { _hex: '0xdefc', _isBigNumber: true },
to: '0xe7f1725E7734CE288F8367e1Bb143E90bb3F0512',
value: BigNumber { _hex: '0x00', _isBigNumber: true },
data: '0x0529568100000000000000000000000070997970c51812dc3a010c7d01b50e0d17dc79c80000000000000000000000000000000000000000000000000000000000000002',
accessList: [],
hash: '0xbf61cf9df3b7bc7df49bb127e23783fad2670d1b7076763d4e6c149864b8972e',
v: 0,
r: '0x56a4faa391111dfd54873dacc9e2b9dbfa47114914c9ca145402c12d1190a353',
s: '0x1b773d3af98496662163600fa7ac81610a32ecf79de3a683ef7ffd606bab8e9a',
from: '0x70997970C51812dc3A010C7d01b50e0d17dc79C8',
confirmations: 0,
wait: [Function (anonymous)],
link: ''
}
create
tableland create <schema> --prefix [prefix]
(string; string)
Create a new table.
Positionals:
schema SQL table schema [string] [required]
prefix The table prefix [string] [optional]
Options:
--help Show help [boolean]
--schema SQL table schema. [string]
--prefix Table name prefix. [string]
-k, --privateKey Private key string [string]
--chain The EVM compatible chain to target
[string] [default: "polygon-mumbai"]
--alchemy Alchemy provider API key [string]
--infura Infura provider API key [string]
--etherscan Etherscan provider API key [string]
Like most relational database systems, Tableland requires the user to create tables for storing, querying, and relating data. See the JavaScript SDK docs for details on create
requirements.
Example
The response from a create
statement includes the created table name
, which the caller can use to make subsequent queries and updates:
tableland create "id int primary key, name text" --prefix "cli_demo_table"
{
meta: {
duration: 128.64695739746094,
txn: {
tableId: '2',
transactionHash: '0x9f51022ba7c82eba2a659d5a9000ba4c70b9f37de77ca299fb17c467d9659178',
blockNumber: 13,
chainId: 31337,
wait: [AsyncFunction: wait],
name: 'cli_demo_table_31337_2',
prefix: 'cli_demo_table'
}
},
success: true,
results: [],
link: ''
}
Since creating a table on requires a smart contract interactions, it is recommended to provide an API key to a remote EVM provider API when using the create
command. This avoids rate limiting by ethers
. For context, Tableland mints a TABLE
(ERC721) token using the Tableland smart contract, which is the on-chain representation of every table then created in Tableland. Simply specify your desired API provider key (or provide all three), and create a table.
info
tableland info <name>
(string)
Get info about a given table by name.
Positionals:
name The target table name [string] [required]
Options:
--help Show help [boolean]
--chain The EVM compatible chain to target
[string] [default: "polygon-mumbai"]
Example
The response includes table information in a standard ERC721 metadata format, including the table’s name, creation data, external URL (which points to the Tableland gateway), and attributes:
tableland info cli_demo_table_31337_2
{
name: 'cli_demo_table_31337_2',
externalUrl: 'http://localhost:8080/chain/31337/tables/2',
animationUrl: 'https://render.tableland.xyz/?chain=31337&id=2',
image: 'https://bafkreifhuhrjhzbj4onqgbrmhpysk2mop2jimvdvfut6taiyzt2yqzt43a.ipfs.dweb.link',
schema: {
columns: [
{ name: 'id', type: 'int', constraints: [ 'primary key' ] },
{ name: 'name', type: 'text' }
]
},
attributes: [ { displayType: 'date', traitType: 'created', value: 1677184456 } ]
}
list
tableland list [address]
(string)
List tables by address.
Positionals:
address The target address [string]
Options:
--help Show help [boolean]
-k, --privateKey Private key string [string] [required]
--chain The EVM compatible chain to target
[string] [default: "polygon-mumbai"]
Using list
command provides and easy way to understand which tables are owned by a certain address.
Example
The retrieved information about those tables includes the table’s name, structure (describing the schema), and created time:
# Be sure to either use the default `polygon-mumabi` or set the `--chain`
tableland list
[
{
tableId: '2',
chainId: 31337
}
]
read
tableland read <query>
(string)
Run a read-only query against a remote table.
Positionals:
query SQL query statement [string] [required]
Options:
--help Show help [boolean]
-c, --chain The EVM chain to target [string] [default: "polygon-mumbai"]
--format Output format. One of 'pretty', 'table', or 'objects'.
[string] [default: "table"]
It is also easy to use vanilla SQL SELECT
statements to query the whole table! See the JavaScript SDK docs for further details. As with the write
command, you must specify the table name returned from the create
command.
Examples for Formatting Outputs
There are three possible --format
options:
table
(default) ⇒ Data returned as an object that represents a table, with two keys called columns and rows; each has column (array of objects) and row (array of arrays) information.pretty
⇒ A tabular view of the data, in a “pretty” table-like view.objects
⇒ The data is returned as an array of objects, where the columns and row data are included in each object; an object represents a row.
tableland read "SELECT * FROM cli_demo_table_80001_1285;" --format <table_objects_or_pretty>
{
meta: { duration: 33.1743745803833 },
success: true,
results: [ { id: 1, name: 'Bobby Tables' } ]
}
If pretty
is flagged, then the output is a “pretty” tabular view for a nice human-readable format:
> tableland read "SELECT * FROM cli_demo_table_80001_1285;" --format pretty
┌─────────┬────┬────────────────┐
│ (index) │ id │ name │
├─────────┼────┼────────────────┤
│ 0 │ 1 │ 'Bobby Tables' │
└─────────┴────┴────────────────┘
Lastly, if you want the data to be returned as objects, use the objects
flag:
> tableland read "SELECT * FROM cli_demo_table_80001_1285;" --format objects
{
meta: { duration: 29.877541542053223 },
success: true,
results: [ { id: 1, name: 'Bobby Tables' } ]
}
receipt
tableland receipt <txn_hash>
(string)
Get the receipt of a chain transaction to know if it was executed, and the execution details.
tableland receipt <hash>
Positionals:
hash Transaction hash [string] [required]
Options:
--help Show help [boolean]
-k, --privateKey Private key string [string] [required]
--chain The EVM compatible chain to target
[string] [default: "polygon-mumbai"]
Example
This allows you to retrieve data like the chain id, block number, and table Id — and note that the transaction hash itself is returned when running the create
and write
commands:
tableland receipt 0x2406508ff28f673e9a080b6295af4cfd0de75a199f2a9044a1cad580cd0aae0a --chain <chanName> --private-key <privateKey>
{
tableId: '2',
transactionHash: '0x2406508ff28f673e9a080b6295af4cfd0de75a199f2a9044a1cad580cd0aae0a',
blockNumber: 135,
chainId: 31337
}
schema
tableland schema <name>
(string)
Get info about a given table schema.
Positionals:
schema SQL table schema [string] [required]
Options:
--help Show help [boolean]
Example
tableland schema cli_demo_table_31337_2
{
columns: [
{ name: 'id', type: 'int', constraints: [ 'primary key' ] },
{ name: 'name', type: 'text' }
]
}
write
tableland write <statement>
(string)
Run a mutating SQL statement against a remote table.
tableland write <statement>
Positionals:
statement SQL write statement [string] [required]
Options:
--help Show help [boolean]
-k, --privateKey Private key string [string]
-r, --rpcRelay Whether writes should be relayed via a validator [boolean]
--chain The EVM compatible chain to target
[string] [default: "polygon-mumbai"]
The write
command allows for vanilla SQL INSERT
, UPDATE
, and DELETE
statements. One key aspect to keep in mind when working with tables is that you must specify the table name
that you get back from the create
command.
Example
Using the write
command will return a value of the blockchain’s transaction hash:
tableland write "INSERT INTO cli_demo_table_31337_2 VALUES (1, 'Bobby Tables');"
{
meta: {
duration: 118.1787919998169,
txn: {
tableId: '2',
transactionHash: '0x2406508ff28f673e9a080b6295af4cfd0de75a199f2a9044a1cad580cd0aae0a',
blockNumber: 135,
chainId: 31337,
wait: [AsyncFunction: wait],
name: 'cli_demo_table_31337_2',
prefix: 'cli_demo_table'
}
},
success: true,
results: [],
link: ''
}
shell
Interact with tableland via an interactive shell environment.
tableland shell
This will open up a shell environment to make it easier to interact with the network:
tableland>
Then, write queries, such as a read statement:
tableland>select * from cli_demo_table_31337_2;
Which will print:
{
meta: { duration: 18.574082374572754 },
success: true,
results: [ { id: 1, name: 'Bobby Tables' } ]
}
{
response: {
meta: { duration: 18.574082374572754 },
success: true,
results: [ { id: 1, name: 'Bobby Tables' } ]
}
}
← Previous
Next →