The Truebit client is a command-line interface (CLI) that allows you to run tasks in the Truebit network.
Installing the Truebit CLI
The Truebit CLI is supported on recent versions of Linux, Windows, and MacOS.
See the Get Started 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:
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
api-auth <namespace> <taskname> <taskId> <authType> <authString> Set API Task authentication
namespace Manage Namespace operations
task Manage Task operations
auth Manage authorization operations
help [command] display help for command
setup
Usage: truebit setup [options]
Setup generate a secret.json in your home directory with your information
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>
-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.
📁 src
📄 main.rs
📁 target
📄 Cargo.toml
📄 Cargo.lock
Running the truebit-cli "build" command automatically generates the target folder and Cargo.lock file.
📁 src
📄 main.c
📄 compile.sh
📁 src
📄 main.cpp
📄 compile.sh
📁 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.
📁 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>
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
