Truebit CLI reference

This guide provides a practical overview of the Truebit CLI, a command-line tool for developers to interact with the Truebit network. It explains how to submit and run computation tasks, manage wallets, monitor task execution, and integrate results into your workflows. Each command comes with detailed help options, making it easy to discover functionality and incorporate the CLI into scripts, automation pipelines, or custom developer tooling.

Installing the Truebit CLI

The Truebit CLI is supported on recent versions of Linux, Windows, and MacOS.

See the Truebit CLI Guide for detailed installation instructions.

Usage: truebit [options] [command]

  _____                _     _ _    __     __        _  __       
 |_   _| __ _   _  ___| |__ (_) |_  \ \   / /__ _ __(_)/ _|_   _ 
   | || '__| | | |/ _ \ '_ \| | __|  \ \ / / _ \ '__| | |_| | | |
   | || |  | |_| |  __/ |_) | | |_    \ V /  __/ |  | |  _| |_| |
   |_||_|   \__,_|\___|_.__/|_|\__|    \_/ \___|_|  |_|_|  \__, |
   ____ _     ___                                          |___/ 
  / ___| |   |_ _|                                               
 | |   | |    | |                                                
 | |___| |___ | |                                                
  \____|_____|___|                                               
                                                                 
A CLI to interact with Truebit Verify node
By accessing and using the Protocol, you hereby agree to our Terms of Use and our Privacy Policy. Patents pending.
Terms of Use: https://www.truebit.io/terms
Privacy Policy: https://www.truebit.io/privacy-policy

Options:
  -V, --version                                                     output the version number
  -h, --help                                                        Display help for command

Commands:
  help [command]                                                    display help for command
  setup                                                             Initialize user profile configuration
  start [options] <taskId> <input>                                  Run a Truebit Task
  deploy [options] <namespace> <taskName>                           Deploy and register a new Truebit Task
  build [options] <sourceCodePath>                                  Create a Function Task
  create-api <manifestPath>                                         Create an API Task
  start-api <manifestPath> <input> [authType] [authString]          Run an API Task
  status <executionId>                                              Get execution status
  quota                                                             Check quota status
  web-login                                                         Sign in to Web UI
  contract                                                          Manage contract bindings
  api-auth <namespace> <taskname> <taskId> <authType> <authString>  Set API Task authentication
  namespace                                                         Manage Namespace operations
  task                                                              Manage Task operations
  auth                                                              Manage authorization operationstrue

Managing Truebit Account

Setup

Usage: truebit setup [options]

Setup generate a secret.json in your home directory with your information

Options:
  -h, --help  Display help for command

Quota

Usage: truebit quota [options]

Displays the current quota status for the registered user, including subscription tier, monthly limits, and reset date.

Options:
  -h, --help  Display help for command

web-login

Usage: truebit web-login [options]

Opens the Truebit Web UI and signs you in automatically using your wallet credentials.

Options:
  -h, --help  Display help for command

chain

Usage: truebit chain [options] [command]

Inspect supported chains.

Options:
  -h, --help      Display help for command

Commands:
  list            Print every supported chainId with its name, symbol, and network class.
  help [command]  display help for command

contract

Usage: truebit contract [options] [command]

Manage contract address bindings for quota enforcement.

Options:
  -h, --help                  Display help for command

Commands:
  add [options] <address>     Bind a contract address to your account.
  remove [options] <address>  Unbind a contract address from your account.
  list                        List all contracts bound to your account.
  help [command]              display help for command

add

Using the “contract add” command, you can associate an existing smart contract that uses Verify Oracles with your Truebit account. Once linked, the contract becomes part of your account, allowing it to benefit from your available quota and the advantages associated with your role.

Usage: truebit contract add [options] <address>

Bind a contract address to your account.

Arguments:
  address            Contract address to bind

Options:
  --chain <chainId>  Numeric chain ID (e.g. 43113 for Avalanche Fuji, 11155111 for Ethereum Sepolia)
  -h, --help         Display help for command

remove

Using the “contract remove” command, you can detach an existing smart contract from your Truebit account. Once removed, the contract will no longer have access to your account quota or the benefits associated with your role.

Usage: truebit contract remove [options] <address>

Unbind a contract address from your account.

Arguments:
  address            Contract address to unbind

Options:
  --chain <chainId>  Numeric chain ID
  -h, --help         Display help for command

list

The “contract list” command displays all smart contracts currently associated with your Truebit account. From here, you can review linked contracts and manage which ones have access to your account quota and role-based benefits.

Usage: truebit contract list [options]

List all contracts bound to your account.

Options:
  -h, --help  Display help for command

Developing Function Tasks

Use the build and start commands to test your function tasks before deploying them to the Coordination Hub.

Build

Usage: truebit build [options] <sourceCodePath>

Compiles source code to obtain compiled and instrumented Truebit task and pushes it to the Truebit node.

Arguments:
  sourceCodePath                     Path of the task source code.

Options:
  -l, --lang [programming-language]  Specify the programming language in which the task was
                                     developed (default: "rs")
  -h, --help                         Display help for command

Output

Building the Function task
Your Function task is ready.
Use the following taskId for execution or deployment: <taskId>

As a result of running the build command, you will receive a TaskId, which serves as the unique identifier for your task.

-l, --lang Options

Language	Value
Rust	rs (default value)
Javascript	js
Python	py
C	c
C++	c++

Example

truebit build examples/js/fibonacci/dist -l js

Source Code Structure

In order to compile your source code, make sure you have the following file structure within the <sourceCodePath> folder that will be built:

Rust

• 📁 src

  • 📄 main.rs

• 📁 target

• 📄 Cargo.toml

• 📄 Cargo.lock

Running the truebit-cli "build" command automatically generates the target folder and Cargo.lock file.

C

• 📁 src

  • 📄 main.c

• 📄 compile.sh

C++

• 📁 src

  • 📄 main.cpp

• 📄 compile.sh

Js

• 📁 src

  • 📄 main.js

• 📁 dist

  • 📄 main.js

• 📄 package-lock.json

• 📄 package.json

• 📄 rollup.config.mjs

The task source filepath must be src/main.js. To create dist/main.js, use the `npx rollup -c` command, as explained in JS Task Preparation.

Python

• 📁 src

  • 📄 task.py

The task source filepath must be src/task.py.

Start

Usage: truebit start [options] <taskId> <input>

Executes a task within the context of Truebit Verify node. The task should be already uploaded to local-storage.

Arguments:
  taskId           Id of the task
  input            Input for task execution

Options:
  --update-config  Automatically update resource limits in config.json according to peak usage
                   report
  -h, --help       Display help for command

Output

Executing the Function task
Function Task executed with status: succeed
Function Task executed with result: 55
Function Task resource usage:
┌───────────────┬───────────────┬───────────────┬───────┬─────────────┬────────────┐
│ (index)       │ Unit          │ Limits        │ Peak  │ Last status │ Capacity   │
├───────────────┼───────────────┼───────────────┼───────┼─────────────┼────────────┤
│ Gas           │ 'Steps'       │ 1099511627776 │ 'N/A' │ 146203      │ '7520445x' │
│ Nested calls  │ 'Calls'       │ 1048576       │ 29    │ 0           │ '36158x'   │
│ Frame memory  │ 'Bytes'       │ 1048576       │ 137   │ 0           │ '7654x'    │
│ System memory │ '64 Kb pages' │ 0             │ 'N/A' │ 'N/A'       │ 'N/A'      │
└───────────────┴───────────────┴───────────────┴───────┴─────────────┴────────────┘

Resources

Name	Description
Gas	Maximum amount of task execution steps.
Call	Amount of nested calls during the task execution.
Frame	Stack memory allocated for the calls.
Memory	Amount of memory used by the task execution.

Metering

Name Name	Description
Limits	Maximum amount of resources assigned to task execution. See determinism.
Peak	Peak resource usage collected during task execution.
Last	The amount of resources in use when the task finished execution. If it ran successfully, the final values for "Call" and "Frame" should be 0.
Capacity	Resources allocated in excess. If the "Limit" value shows a 4000x number, it means that the required resources exceed the actual needs by that amount. Remember: resource usage might vary on the same Truebit task depending on the input data.

For more information about the use of the Resources, please check the Instrumentation page

Developing API Tasks

Use the start-api, create-api commands to test your API tasks before deploying them to the Coordination Hub:

start-api

Usage: truebit start-api [options] <manifestPath> <input> [authType] [authString]

Start the Truebit API Task, verify with enforcer and request the api. As a result, it returns the
API response

Arguments:
  manifestPath  Path of the manifest.
  input         Input request JSON file path
  authType      Type of authentication needed for API task usage. One of:
                <aws-signature,basic-auth,custom-header>
  authString    Auth string is a comma separated value that represents auth method.
  
  	Examples:
  		AWS_SIGNATURE = "accessKey:<accesskey>,secretKey:<secretkey>"
  		BASIC_AUTH = "username:<username>,password:<password>"
  		CUSTOM_HEADER = "<customheader>"

Options:
  -h, --help    Display help for command

Output

Executing the API task
API Task executed with status: ['OK', 'Error']
API Task Output
Input request
{
    path: '',
    method: ['POST','GET','DELETE','PUT','PATCH'],
    body: {
    },
    params:
  }
Base URL =
OpenAPI manifest check - ['OK', 'Error']
API Task response
{
}

Name	Description
path	API endpoint path.
method	["GET", "POST", "DELETE", "PUT", "PATCH"]
body	API input parameters.
params	API input parameters.
Base URL	API Base URL.
OpenAPI Manifest check	Manifest check. OK: Manifest is well written and executed. FAIL: There are errors on the manifest schema.
API Task response	API endpoint output.

create-api

Create the Truebit API Task and upload the Manifest to the local storage. As a result, it returns the taskId.
  
Usage:
  truebit create-api [options] <manifestPath>

Arguments:
  <manifestPath>  Path of the manifest.

OPTIONS:
  -h, --help    display help for command

Output

Executing the API task.
Your API task is ready.
Use the following taskId for execution or deployment: <taskId>

Check this example to get more details about the Truebit API Task Manifest.

Deploying Truebit Tasks

Use the deploy command to deploy your Truebit Task to the Coordination Hub. If API task authentication is required, use the api-auth command.

deploy

Usage: truebit deploy [options] <namespace> <taskName>

Deploys and registers a new Truebit task specified by the --taskId parameter. Using the deploy command makes the Truebit task available for execution.

Arguments:
  namespace          Namespace to register the task in (lowercase)
  taskName           Name of the task (lowercase)

Options:
  --taskId <taskId>  Id of the task <Required>
  --meta <meta>      Meta information for the task (string between single quotes)
  -h, --help         Display help for command

Output

The function task has been deployed successfully.
The Task <taskName> version <version> was registered successfully in namespace <namespace>

api-auth

Usage: truebit api-auth [options] <namespace> <taskname> <taskId> <authType> <authString>

Specify authentication for a truebit api task

Arguments:
  namespace   Namespace to register
  taskname    Taskname to register
  taskId      Id of the task
  authType    Type of authentication need for api task usage. One of: <aws-signature,basic-auth,custom-header>
  authString  Auth string is a comma separated value that represent auth method.
  
  	Examples:
  		AWS_SIGNATURE = "accessKey:<accesskey>,secretKey:<secretkey>"
  		BASIC_AUTH = "username:<username>,password:<password>"
  		CUSTOM_HEADER = "<customheader>"

Options:
  -h, --help  Display help for command

Only the user who deployed the task can upload the credentials.

Output

Deploying the API Authentication credentials
The credentials were deployed successfully

Managing Truebit Tasks

Use the namespace and task commands to manage access to your Truebit Tasks within your development team. To grant execution access for a deployed task, use the auth command.

namespace

Usage: truebit namespace [options] [command]

The namespace command helps you group and manage different tasks under a single name, like an umbrella.
This name, called a namespace, can be anything that represents your tasks, such as the name of your company. Each task you create will be associated with a namespace.

Options:
  -h, --help                      Display help for command

Commands:
  register <namespace>            Register a new namespace
  transfer <namespace> <address>  Transfer a namespace
  grant <namespace> <address>     Grant access to a namespace
  revoke <namespace> <address>    Revoke access to a namespace
  help [command]                  display help for command

namespace register

Usage: truebit namespace register [options] <namespace>

Register a new namespace. The user who calls this command will become the owner of the registered namespace. Each namespace can have only one owner. The owner can grant access to other users using the grant command.

Arguments:
  namespace   Namespace to register

Options:
  -h, --help  Display help for command

Output

Registering namespace <namespace>
The Namespace <namespace> has been successfully registered.

namespace transfer

AVAX funds are required to execute this command.

Usage: truebit namespace transfer [options] <namespace> <address>

Change the owner of a namespace.
Only the current owner can use this command to grant access.

Arguments:
  namespace   Namespace to transfer
  address     Address to transfer namespace to

Options:
  -h, --help  Display help for command

Output

Transferring namespace <namespace> to the address <address>
The Namespace <namespace> has been successfully transferred to the <address>.

namespace grant

AVAX funds are required to execute this command.

Usage: truebit namespace grant [options] <namespace> <address>

Give a user access to the namespace.
Only the current owner can use this command to grant access.

Arguments:
  namespace   Namespace to grant access to
  address     Address to grant access to

Options:
  -h, --help  Display help for command

Output

Granting access to namespace <namespace> to the address <address>
The address <address> now has access to the namespace <namespace>.

namespace revoke

AVAX funds are required to execute this command.

Usage: truebit namespace revoke [options] <namespace> <address>

Take away a user's access to the namespace.
Only the current owner can use this command to revoke access.

Arguments:
  namespace   Namespace to revoke access from
  address     Address to revoke access from

Options:
  -h, --help  Display help for command

Output

Revoking access to namespace <namespace> to the address <address>
The address <address> does not have access to the namespace <namespace>.

task

Usage: truebit task [options] [command]

Manages tasks within a specified namespace, facilitating the organization, tracking, and management of tasks across different projects or domains. This command serves as a gateway to various task-related operations such as registration, modification, and querying, thereby
enhancing project management and operational efficiency.

Options:
  -h, --help                                 Display help for command

Commands:
  label [options] <namespace> <taskName>     Assign a label to a registered task.
  disable [options] <namespace> <taskName>   Disable a registered task.
  enable [options] <namespace> <taskName>    Enable a registered task.
  get-task [options] <namespace> <taskName>  Retrieve information from a namespace and a taskName
  help [command]                             display help for command

task label

AVAX funds are required to execute this command.

Usage: truebit task label [options] <namespace> <taskName>

Set label for a task in a namespace

Arguments:
  namespace        Namespace of the task
  taskName         Name of the task

Options:
  --label <label>  Label for the task <Required>
  --ver <version>  Version of the task <Required>
  -h, --help       Display help for command

Output

Setting label {label} for the task: {taskName}.
The Label {label} has been successfully set for the task {taskName}.

task disable

AVAX funds are required to execute this command.

Usage: truebit task disable [options] <namespace> <taskName>

Disable task in a namespace --ver <version> or --label <label> can be used to disable specific task

Arguments:
  namespace        Namespace of the task
  taskName         Name of the task

Options:
  --ver <version>  Version of the task to disable <Required>
  --label <label>  Label for the task to disable <Required>
  -h, --help       Display help for command

Output

Disabling task {taskName}.
The Task {taskName} has been successfully disabled.

task enable

AVAX funds are required to execute this command.

Usage: truebit task enable [options] <namespace> <taskName>

Enable a task in a namespace --ver <version> or --label <label> can be used to enable specific task

Arguments:
  namespace            Namespace of the task
  taskName             Name of the task

Options:
  --ver <version>  Version of the task <Optional>
  --label <label>  Label for the task <Optional>
  -h, --help       Display help for command

Output

Enabling task {taskName}.
The Task {taskName} has been successfully enabled.

task get-task

Usage: truebit task get-task [options] <namespace> <taskName>

Get task information from a namespace and a taskname --ver or --label can be used to get specific task

Arguments:
  namespace        Namespace of the task
  taskName         Name of the task

Options:
  --ver <version>  Version of the task <Optional>
  --label <label>  Label for the task <Optional>
  -h, --help       Display help for command

Output

Getting information from the task {taskName}
{
  namespace: {namespace},
  taskId: {taskId},
  version: {version},
  meta: {metadata},
  nameSpaceOwner: {owner}
}

auth

Usage: truebit auth [options] [command]

The auth command is responsible for managing the authorization for task execution. It allows the namespace owner to grant or deny access to addresses, ensuring that only authorized individuals can execute specific tasks.

Options:
  -h, --help                                 Display help for command

Commands:
  grant <namespace> <grantee>                Grant authorization to a grantee
  revoke <namespace> <grantee>               Revoke authorization from a grantee
  register <apiKey>                          Register an authorized API key
  deregister <apiKey>                        Deregister an authorized API key
  check-authorization <namespace> <grantee>  Check if an address is authorized
  get-payer <apiKeyHash>                     Get payer address from an API key
  new-apikey                                 Generate a new Api Key
  help [command]                             display help for command

auth grant

AVAX funds are required to execute this command.

Usage: truebit auth grant [options] <namespace> <grantee>

The auth grant command is responsible for granting access to a specific address within a namespace. The grantee will have the ability to execute the tasks stored within that namespace.

Arguments:
  namespace   Namespace containing the desired tasks
  grantee     Grantee to be authorized

Options:
  -h, --help  Display help for command

Output

Granting authorization to <grantee> in the namespace <namespace>
Authorization granted to <grantee> in the namespace <namespace>

auth revoke

AVAX funds are required to execute this command.

Usage: truebit auth revoke [options] <namespace> <grantee>

The auth revoke command is responsible for revoking access from a specific address within a namespace. This command ensures that the specified address can no longer execute the tasks stored within that namespace.

Arguments:
  namespace   Namespace containing the desired tasks
  grantee     Grantee to be unauthorized

Options:
  -h, --help  Display help for command

Output

Revoking authorization from <grantee> in the namespace <namespace>
Authorization revoked from <grantee> in the namespace <namespace>

auth register

AVAX funds are required to execute this command.

Usage: truebit auth register [options] <apiKey>

The auth register command is responsible for registering a specific API_KEY. Every execution made with this API_KEY will be charged to the user who registered it. This way, you can ensure that the user who registered the API_KEY is responsible for paying for all executions made with it.

Arguments:
  apiKey      API key to be registered

Options:
  -h, --help  Display help for command

Output

Registering API key <apiKey>
The API key <apiKey> was registered with the hash: <hashedApiKey>

auth deregister

AVAX funds are required to execute this command.

Usage: truebit auth deregister [options] <apiKey>

The auth deregister command will revoke access to a specific API_KEY. After deregistration, any execution attempt using this API_KEY will result in a "not authorized" message.

Arguments:
  apiKey      API key to be deregistered

Options:
  -h, --help  Display help for command

Output

Deregistering API key <apiKey>
The API key <apiKey> was successfully deregistered

auth check-authorization

Usage: truebit auth check-authorization [options] <namespace> <grantee>

The auth check-authorization command verifies if a specific address has permission to execute tasks in a particular namespace.

Arguments:
  namespace   Namespace of the tasks
  grantee     Check authorization for the grantee

Options:
  -h, --help  Display help for command

Output

Checking authorization for <grantee> in namespace <namespace>
Grantee <grantee> is authorized in namespace <namespace>

auth get-payer

Usage: truebit auth get-payer [options] <apiKeyHash>

The auth get-payer command retrieves the payer address associated with a specific API_KEY.

Arguments:
  apiKeyHash  API key hash

Options:
  -h, --help  Display help for command

Output

Getting payer address from <apiKeyHash>
The payer address from the API Key Hash: <apiKeyHash> is <payerAddress>

auth new-apikey

Usage: truebit auth new-apikey [options]

Generate a new Api Key to be used for execution payment. The Api Key is a
unique identifier for the payer.

Options:
  -h, --help  Display help for command

Output

Api Key: <uuid>

secret.json

The secret.json file is generated when you accept the Terms and Conditions for the first time. It stores essential user information, including your wallet and private key. Keep this file secure, as it contains your credentials for accessing Truebit Verify.

{
  "privateKey": "0x************************************f108",    
  "address": "0x************************************6670F",
  "eula": "1740428091368"
  "RPC_URL": ""
}

Parameter	Description
privateKey	Your private key
address	Your wallet address
eula	Eula acceptance timestamp
RPC_URL