# 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.

{% hint style="info" %}
**Installing the Truebit CLI**

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

See the [Truebit CLI Guide](/overview/getting-started-guide.md) for detailed installation instructions.
{% endhint %}

{% code overflow="wrap" fullWidth="true" %}

```
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
```

{% endcode %}

### 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](/architecture/introduction.md#truebit-verify-hub).

#### Build

{% code overflow="wrap" %}

```
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

```

{% endcode %}

#### Output

{% code overflow="wrap" %}

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

{% endcode %}

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

<table><thead><tr><th width="138">Language</th><th>Value</th></tr></thead><tbody><tr><td><strong>Rust</strong></td><td><strong>rs  (default value)</strong></td></tr><tr><td>Javascript</td><td>js</td></tr><tr><td>Python</td><td>py</td></tr><tr><td>C</td><td>c</td></tr><tr><td>C++</td><td>c++</td></tr></tbody></table>

#### 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:

{% tabs %}
{% tab title="Rust" %}

* 📁 src&#x20;
  * 📄 main.rs&#x20;
* 📁 target
* 📄 Cargo.toml
* 📄 Cargo.lock

{% hint style="info" %}
Running the truebit-cli "build" command automatically generates the **target** folder and **Cargo.lock** file.&#x20;
{% endhint %}
{% endtab %}

{% tab title="C" %}

* 📁 src&#x20;
  * 📄 main.c
* 📄 compile.sh
  {% endtab %}

{% tab title="C++" %}

* 📁 src&#x20;
  * 📄 main.cpp
* 📄 compile.sh
  {% endtab %}

{% tab title="Js" %}

* 📁 src&#x20;
  * 📄 main.js
* 📁 dist
  * 📄 main.js
* 📄 package-lock.json
* 📄 package.json
* 📄 rollup.config.mjs

{% hint style="info" %}
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](/developing-truebit-tasks/how-to-create-function-tasks/supported-languages/javascript.md#task-preparation).
{% endhint %}
{% endtab %}

{% tab title="Python" %}

* 📁 src&#x20;
  * 📄 task.py

{% hint style="info" %}
The task source filepath must be **src/task.py**.
{% endhint %}
{% endtab %}
{% endtabs %}

#### Start

{% code overflow="wrap" %}

```
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


```

{% endcode %}

#### Output

```bash
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**

<table><thead><tr><th width="118">Name</th><th>Description</th></tr></thead><tbody><tr><td>Gas</td><td>Maximum amount of task execution steps.</td></tr><tr><td>Call</td><td>Amount of nested calls during the task execution.</td></tr><tr><td>Frame</td><td>Stack memory allocated for the calls.</td></tr><tr><td>Memory</td><td>Amount of memory used by the task execution.</td></tr></tbody></table>

#### Metering

<table><thead><tr><th width="119">Name                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             Name</th><th>Description</th></tr></thead><tbody><tr><td><strong>Limits</strong></td><td>Maximum amount of resources assigned to task execution. See <a href="/pages/9QdmubpyGCMsA5O2eUHL">determinism</a>.</td></tr><tr><td><strong>Peak</strong></td><td>Peak resource usage collected during task execution.</td></tr><tr><td><strong>Last</strong></td><td>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.</td></tr><tr><td><strong>Capacity</strong></td><td><p>Resources allocated in excess. <br>If the "Limit" value shows a 4000x number, it means that the required resources exceed the actual needs by that amount.</p><p>Remember: resource usage might vary on the same Truebit task depending on the input data.</p></td></tr></tbody></table>

{% hint style="info" %}
For more information about the use of the Resources, please check the [Instrumentation](/developing-truebit-tasks/how-to-create-function-tasks/key-concepts/task-instrumentation.md) page
{% endhint %}

### Developing API Tasks

Use the `start-api`, `create-api` commands to test your API tasks before deploying them to the [Coordination Hub](/architecture/introduction/truebit-verify-hub.md):

#### start-api

{% code overflow="wrap" %}

```
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

```

{% endcode %}

#### Output

```bash
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
{
}
```

<table><thead><tr><th width="180">Name</th><th>Description</th></tr></thead><tbody><tr><td>path</td><td>API endpoint path.</td></tr><tr><td>method</td><td>["GET", "POST", "DELETE", "PUT", "PATCH"]</td></tr><tr><td>body</td><td>API input parameters.</td></tr><tr><td>params</td><td>API input parameters.</td></tr><tr><td>Base URL</td><td>API Base URL.</td></tr><tr><td>OpenAPI Manifest check</td><td>Manifest check. <br>OK: Manifest is well written and executed.<br>FAIL: There are errors on the manifest schema.</td></tr><tr><td>API Task response</td><td>API endpoint output.</td></tr></tbody></table>

### create-api

{% code overflow="wrap" %}

```
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
```

{% endcode %}

#### Output

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

{% hint style="info" %}
Check this [example](/developing-truebit-tasks/how-to-create-api-tasks/api-task-examples.md) to get more details about the [Truebit API Task ](/developing-truebit-tasks/how-to-create-api-tasks.md)Manifest.
{% endhint %}

### 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

{% code overflow="wrap" %}

```
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
```

{% endcode %}

#### Output

<pre class="language-bash" data-overflow="wrap"><code class="lang-bash"><strong>The function task has been deployed successfully.
</strong>The Task &#x3C;taskName> version &#x3C;version> was registered successfully in namespace &#x3C;namespace>
</code></pre>

### **api-auth**

{% code overflow="wrap" %}

```
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
```

{% endcode %}

{% hint style="danger" %}
Only the user who deployed the task can upload the credentials.&#x20;
{% endhint %}

#### Output

```bash
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

{% code overflow="wrap" %}

```
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

```

{% endcode %}

#### namespace register

{% code overflow="wrap" %}

```
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

```

{% endcode %}

#### Output

<pre class="language-bash"><code class="lang-bash">Registering namespace &#x3C;namespace>
<strong>The Namespace &#x3C;namespace> has been successfully registered.
</strong></code></pre>

#### namespace transfer

{% hint style="info" %}
AVAX funds are required to execute this command.
{% endhint %}

{% code overflow="wrap" %}

```
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

```

{% endcode %}

#### Output

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

#### namespace grant

{% hint style="info" %}
AVAX funds are required to execute this command.
{% endhint %}

{% code overflow="wrap" %}

```
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

```

{% endcode %}

#### Output

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

#### namespace revoke

{% hint style="info" %}
AVAX funds are required to execute this command.
{% endhint %}

{% code overflow="wrap" %}

```
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

```

{% endcode %}

#### Output

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

### task

{% code overflow="wrap" %}

```
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
```

{% endcode %}

#### task label

{% hint style="info" %}
AVAX funds are required to execute this command.
{% endhint %}

{% code overflow="wrap" %}

```
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

```

{% endcode %}

#### Output

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

#### task disable

{% hint style="info" %}
AVAX funds are required to execute this command.
{% endhint %}

{% code overflow="wrap" %}

```
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

```

{% endcode %}

#### Output

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

#### task enable

{% hint style="info" %}
AVAX funds are required to execute this command.
{% endhint %}

{% code overflow="wrap" %}

```
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

```

{% endcode %}

#### Output

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

#### task get-task

{% code overflow="wrap" %}

```
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

```

{% endcode %}

#### Output

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

### auth

{% code overflow="wrap" %}

```
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
```

{% endcode %}

#### auth grant

{% hint style="info" %}
AVAX funds are required to execute this command.
{% endhint %}

{% code overflow="wrap" %}

```
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
```

{% endcode %}

#### Output

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

#### auth revoke

{% hint style="info" %}
AVAX funds are required to execute this command.
{% endhint %}

<pre data-overflow="wrap"><code><strong>Usage: truebit auth revoke [options] &#x3C;namespace> &#x3C;grantee>
</strong>
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
</code></pre>

#### Output

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

#### auth register

{% hint style="info" %}
AVAX funds are required to execute this command.
{% endhint %}

{% code overflow="wrap" %}

```
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
```

{% endcode %}

#### Output

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

#### auth deregister

{% hint style="info" %}
AVAX funds are required to execute this command.
{% endhint %}

{% code overflow="wrap" %}

```
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
```

{% endcode %}

#### Output

<pre><code>Deregistering API key &#x3C;apiKey>
<strong>The API key &#x3C;apiKey> was successfully deregistered
</strong></code></pre>

#### auth check-authorization

<pre data-overflow="wrap"><code>Usage: truebit auth check-authorization [options] &#x3C;namespace> &#x3C;grantee>
<strong>
</strong>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
</code></pre>

#### Output

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

#### auth get-payer

{% code overflow="wrap" %}

```
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
```

{% endcode %}

#### 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

```bash
Api Key: <uuid>
```

## secret.json

The `secret.json` file is generated when you accept the Terms and Conditions for the first time. I**t 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": ""
}
```

<table><thead><tr><th align="center">Parameter</th><th align="center" valign="middle">Description</th></tr></thead><tbody><tr><td align="center">privateKey</td><td align="center" valign="middle">Your private key</td></tr><tr><td align="center">address</td><td align="center" valign="middle">Your wallet address</td></tr><tr><td align="center">eula</td><td align="center" valign="middle">Eula acceptance timestamp</td></tr><tr><td align="center">RPC_URL</td><td align="center" valign="middle"></td></tr></tbody></table>


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://devs.truebit.io/developing-truebit-tasks/truebit-cli-reference.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.