# Usage

### CLI utility

This guide covers common workflows using the **Loci CLI**, which enables seamless interaction with the Loci AI Binary Analysis platform directly from your terminal.

#### Available commands

list-projects, list-versions, last-version, upload, upload-last, status, func-insights, flame-graph, whoami

List existing projects:

{% code title="Command" %}

```bash
loci_api list-projects
```

{% endcode %}

Example:

{% code title="Example" %}

```bash
$ python -m loci_api list-projects
[
    "OpenSSL"
]
```

{% endcode %}

List all versions for a project:

{% code title="Command" %}

```bash
loci_api list-versions <project-name>
```

{% endcode %}

Example:

{% code title="Example" %}

```bash
$ python -m loci_api list-versions OpenSSL
[
    "1.1.1",
    "3.1.4"
]
```

{% endcode %}

Get latest valid version for a project:

{% code title="Command" %}

```bash
loci_api last-version <project-name>
```

{% endcode %}

Example:

{% code title="Example" %}

```bash
$ python -m loci_api last-version OpenSSL
[
    "3.1.4"
]
```

{% endcode %}

Upload new version:

{% code title="Commands" %}

```bash
loci_api upload <path-to-binary> <project-name> <new-version-name> [--compare-version-name version-name]
loci_api upload-last <path-to-binary> <project-name> <new-version-name>
```

{% endcode %}

Get function insights:

{% code title="Command" %}

```bash
loci_api func-insights <project-name> <version-name> [--version-name-base <base-version-name>] [--perc-resp-limit <percentage>] [--perc-thro-limit <percentage>] [--perc-bott-limit <percentage>] [--pairs <func1> <bin1> ...]
```

{% endcode %}

Example:

{% code title="Example" %}

```bash
$ python -m loci_api func-insights "OpenSSL" "3.1.4" --version-name-base="1.1.1" --perc-resp-limit=20 --pairs asn1_str2type libcrypto.so asn1_str2tag libcrypto.so
[
    {
        "total_count": "17294",
        "binary_name": "libcrypto.so",
        "function_long_name": "asn1_gen.c_asn1_str2tag",
        "function_name": "asn1_str2tag",
        "source_location": "/tmp/tmpqubfnl76/crypto/asn1/asn1_gen.c:503:566;",
        "mean_bottleneck": null,
        "std_bottleneck": null,
        "mean_throughput": 269.44492,
        "std_throughput": 18.811226,
        "mean_response": 506.63327,
        "std_response": 18.811226,
        "mean_bottleneck_base": null,
        "std_bottleneck_base": null,
        "mean_throughput_base": 264.7869,
        "std_throughput_base": 18.811226,
        "mean_response_base": 282.73398,
        "std_response_base": 18.811226,
        "perc_throughput": "1.8",
        "perc_response": "79.2",
        "perc_bottleneck": null
    },
    {
        "total_count": "17294",
        "binary_name": "libcrypto.so",
        "function_long_name": "asn1_gen.c_asn1_str2type",
        "function_name": "asn1_str2type",
        "source_location": "/tmp/tmpqubfnl76/crypto/asn1/asn1_gen.c:579:586;",
        "mean_bottleneck": null,
        "std_bottleneck": null,
        "mean_throughput": 2087.0325,
        "std_throughput": 77.55288,
        "mean_response": 2771728,
        "std_response": 77.55288,
        "mean_bottleneck_base": null,
        "std_bottleneck_base": null,
        "mean_throughput_base": 1799.3105,
        "std_throughput_base": 77.55288,
        "mean_response_base": 16767339,
        "std_response_base": 77.55288,
        "perc_throughput": "16.0",
        "perc_response": "-83.5",
        "perc_bottleneck": null
    }
]
```

{% endcode %}

Get flame graph:

{% code title="Command" %}

```bash
loci_api flame-graph <project-name> <version-name> [---function-name <function_name>] [--binary-name <binary-name>]
```

{% endcode %}

Example:

{% code title="Example" %}

```bash
$loci_api flame-graph seoul_test main@46943b6 --function-name main --binary-name build.bin.demo_arm64
[{"low":130,"high":137,"x":-3,"name":"feature_load_from_nvm","id":22,"value":7},{"low":525,"high":532,"x":-3,"name":"feature_load_from_nvm","id":22,"value":7},{"low":539,"high":544,"x":-3,"name":"feature_save_to_nvm","id":23,"value":5},{"low":598,"high":605,"x":-3,"name":"__stack_chk_fail@GLIBC_2.17@plt","id":3,"value":7},{"low":68,"high":75,"x":-2,"name":"feature_load_from_nvm","id":22,"value":7},{"low":79,"high":88,"x":-2,"name":"drive_mode_init","id":20,"value":9},{"low":91,"high":100,"x":-2,"name":"blink_init","id":11,"value":9},{"low":104,"high":110,"x":-2,"name":"ambient_init","id":8,"value":6},{"low":127,"high":137,"x":-2,"name":"uds_init","id":27,"value":10},{"low":145,"high":150,"x":-2,"name":"feature_save_to_nvm","id":23,"value":5},{"low":154,"high":161,"x":-2,"name":"ambient_set_target","id":9,"value":7},{"low":179,"high":269,"x":-2,"name":"blink_update","id":12,"value":90},{"low":272,"high":310,"x":-2,"name":"ambient_tick","id":10,"value":38},{"low":324,"high":331,"x":-2,"name":"__printf_chk@GLIBC_2.17@plt","id":2,"value":7},{"low":351,"high":394,"x":-2,"name":"can_pack_VehDynA","id":13,"value":43},{"low":412,"high":419,"x":-2,"name":"__printf_chk@GLIBC_2.17@plt","id":2,"value":7},{"low":441,"high":606,"x":-2,"name":"uds_handle","id":26,"value":165},{"low":615,"high":622,"x":-2,"name":"__printf_chk@GLIBC_2.17@plt","id":2,"value":7},{"low":651,"high":658,"x":-2,"name":"__printf_chk@GLIBC_2.17@plt","id":2,"value":7},{"low":695,"high":702,"x":-2,"name":"puts@GLIBC_2.17@plt","id":25,"value":7},{"low":706,"high":735,"x":-2,"name":"drive_mode_set","id":21,"value":29},{"low":742,"high":749,"x":-2,"name":"__printf_chk@GLIBC_2.17@plt","id":2,"value":7},{"low":0,"high":787,"x":-1,"name":"main","id":24,"value":787}]
```

{% endcode %}

Check authentication status:

{% code title="Command" %}

```bash
loci_api whoami
```

{% endcode %}

Example:

{% code title="Example" %}

```bash
$loci_api whoami
Company: AL Agentic Company
Agentic: Yes
Max users: 100
Created at: 2025-10-30T11:40:13.074Z
Active until: undefined
```

{% endcode %}

***

### Python Module

Example Python script for a common workflow using the **loci\_api** python module.

#### Binary Upload example python script

{% code title="upload\_binary.py" %}

```python
import sys
from loci_api import api_helper

if __name__ == "__main__":

    # input params
    file_path = sys.argv[1]
    version_name = sys.argv[2]
    platform = sys.argv[3]
    project_name = sys.argv[4]

    project_id = api_helper.get_project_id(project_name)
    if project_id is None:
        print("Uploading failed, Project does not exist.")
        exit(-1)

    compare_version_id = api_helper.get_last_version_id(project_id)
    reportId = api_helper.upload_binary(file_path, version_name, compare_version_id, project_id, platform)

    if reportId != '':
        print(f"Uploaded binary Report ID: {reportId}, Compare Version ID: {compare_version_id}, Project ID: {project_id}")
    else:
        print("Uploading failed, See previous message for more details.")
        exit(-1)

    finished = False
    status = 0

    print("Waiting for processing to finish")
    while not finished:
        finished, status = api_helper.upload_finished(project_id, reportId)
        time.sleep(10)

    return status
```

{% endcode %}