# CLI

{% hint style="info" %}
The agent stores its configuration in the hidden **.datasentinel** directory within the user's home directory, using two files: **agent.yml** and **connections.yml**.\
These files can be manually managed if necessary.
{% endhint %}

## **Prerequisites**

Enable the execution of the CLI

* Using an alias

```bash
alias datasentinel='DATASENTINEL_PATH=<<INSTALL_DIRECTORY>>/datasentinel;LD_LIBRARY_PATH=$DATASENTINEL_PATH/lib/ $DATASENTINEL_PATH/datasentinel'
```

* Using environment variables

```bash
export DATASENTINEL_PATH="<<INSTALL_DIRECTORY>>/datasentinel"
export LD_LIBRARY_PATH=$DATASENTINEL_PATH/lib:$LD_LIBRARY_PATH
export PATH=$DATASENTINEL_PATH:$PATH
```

## **Agent Management**

### Show Commands

* Simply enter the **datasentinel** command.

```bash
datasentinel
```

{% code title="Response" %}

```
Copyright 2026 (c) Datasentinel- All rights reserved        www.datasentinel.io
================================================================================

   Agent:
         - start agent
         - stop agent
         - status agent
         - show metrics
                Show internal agent metrics and cache activity
         - set port <port number>
         - set collection-rate <low|high>
                low: The sessions collection is done every 10 seconds
                high: The sessions collection is done every second  (Default value)
                If the datasentinel extension is not installed, the collection-rate is automatically adjusted to low value 
         - set tables-monitoring-limit (default 1000)
                The agent monitors the activity of tables and indexes if the number of tables in the connection is less than the defined limit
         - set query-monitoring-limit (default 30000)
                The agent tracks query activity, storing unique IDs in a daily cache. Exceeding limit triggers automatic deactivation of query monitoring.
         - set use-postgres-queryid <on|off>    (default off) 
                If on, the query_md5_id tag contains PostgreSQL’s internal query identifier (queryid) instead of an MD5 hash computed from the query text (across all connections >= PostgreSQL 14).
   Connections: when the connections are disabled, the agent is disconnected.
         - enable all
         - disable all

   Connection:
         - add connection <name> -f <json file>
         - update connection <name> -f <json file>
                json example: {
                                "host": "hostname",
                                "port": 4587,
                                "user": "username",
                                "password": "value",
                                "tags": "key=value,key=value,..."
                              }

         - update connection <name> samples <on|off> (default off)
                Collect and send sample queries, with literal values if present

         - update connection <name> lock-monitoring <on|off> (default on)
                Scan blocking sessions (longer than lock-monitoring-delay) and send blocking reports 

         - update connection <name> lock-monitoring-delay <seconds> (default 30)
                Minimum number of seconds before triggering a blocking scenario 
              
         - update connection <name> table-monitoring <on|off> (default on)
                Monitor the activity of tables and indexes (The number of tables must be lower than the maximum limit set at the agent level (default 1000)

         - update connection <name> query-monitoring <on|off> (default on)
                Monitor pg_stat_statements query activity
       
         - update connection <name> query-monitoring-optimize <on|off> (default on)
                Group similar pg_stat_statements queries           
        
         - update connection <name> query-monitoring-min-calls <calls> (default 2)
         - update connection <name> query-monitoring-min-time <seconds> (default 1)
                Retrieve pg_stat_statements queries executed n times (calls) OR with total execution time exceeding specified seconds
           
         - update connection <name> test-query-monitoring-optimize
                Test and optimize pg_stat_statements query contents with previous parameters, display results

         - update connection <name> use-postgres-queryid <on|off> (default off)
                If on, the query_md5_id tag contains PostgreSQL’s internal query identifier (queryid) instead of an MD5 hash computed from the query text (for versions >= 14)
                Inherits the global agent setting if not defined at connection level
                              
         - delete connection <name>
         - enable connection <name>
         - disable connection <name>

         - show connections
         - show connection <name>
    
    Dump connection in JSON format:
         - dump connection <name>  

    Upload server:
         - set server <host> <port>
         - show server
         - test server

    Token:
         - set token <value>
         - show token
         
    Proxy:
         - set proxy -f <json file>
                json example: {
                                "host": "hostname",
                                "port": 4587,
                                "user": "username (optional)",
                                "password": "value (optional)"
                              }
         - delete proxy
         - show proxy



```

{% endcode %}

### Status

```bash
datasentinel status agent
```

{% code title="Response" %}

```
Copyright 2026 (c) Datasentinel- All rights reserved        www.datasentinel.io
================================================================================

               Agent
                  Version : 3.9.0                                             
                   Server : pg-crm-4743                                       
                     Port : 8282                                              
               Start time : 2026-01-29 18:06:43                               
          Collection rate : low                                               
   Table monitoring limit : 1000                                              
   Query monitoring limit : 30000                                             
     Use postgres queryid : off                                               
             Sql max size : 256000                                            

               Proxy
                     host :                                                   
                     port : 0                                                 
                     user :                                                   
                 password :                                                   

              Upload
                     host : demo.datasentinel.io                              
                     port : 443                                               

         Connections
                 declared : 1                                                 
                  running : 1                                                 
              not running : 0   
```

{% endcode %}

### Start

```bash
datasentinel start agent
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Starting the agent...


To show the status : datasentinel status agent
```

{% endcode %}

### Stop

```bash
datasentinel stop agent
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

The agent is stopped!
```

{% endcode %}

### Change Port Number

> By default, the agent is configured to listen on port 8282, enabling API or CLI calls to be made.

```bash
datasentinel set port 9121
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Agent port successfully set! The agent has been stopped, you need to restart it
```

{% endcode %}

### Change Table Monitoring Limit

```bash
datasentinel set tables-monitoring-limit <limit>
```

* Parameter:

  > The limit number.\
  > The agent tracks the activity of tables and indexes if the connection’s table count is below the set limit (default **1000**).

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Tables monitoring limit successfully set to 3000!


                Agent
                    Version : 3.2.0
                    Server : pgsentinel.localdomain
                      Port : 8282
                Start time : 2023-01-31 13:08:27
            Collection rate : low
    Table monitoring limit : 2500
    Query monitoring limit : 35000
              Sql max size : 7512453

                Proxy
                      host :
                      port : 0
                      user :
                  password :

                Upload
                      host : 163.172.135.154
                      port : 443

          Connections
                  declared : 2
                    running : 1
                not running : 1
```

{% endcode %}

### Change Query monitoring Limit

> Since agent version 3.2

```bash
datasentinel set query-monitoring-limit <limit>
```

* Parameter:

  > The limit number.\
  > The agent tracks query activity, storing unique IDs in a daily cache. Exceeding limit triggers automatic deactivation of query monitoring. (default 30000)

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Tables monitoring limit successfully set to 3000!


                Agent
                    Version : 3.2.0
                    Server : pgsentinel.localdomain
                      Port : 8282
                Start time : 2023-01-31 13:08:27
            Collection rate : low
    Table monitoring limit : 2500
    Query monitoring limit : 35000
              Sql max size : 7512453

                Proxy
                      host :
                      port : 0
                      user :
                  password :

                Upload
                      host : 163.172.135.154
                      port : 443

          Connections
                  declared : 2
                    running : 1
                not running : 1
```

{% endcode %}

### Change Use Postgres Queryid

> Since agent version 3.9

```bash
datasentinel set use-postgres-queryid on|off
```

* Parameter:

  > Enable or disable the use of `queryid` as the query identifier in the UI.\
  > Refer to the [detailed documentation](/manual/features/tips-and-hints/query-identifier.md) for more information.

{% code title="Response" %}

```
Copyright 2026 (c) Datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Usage of postgres queryid successfully set to on!


               Agent
                  Version : 3.9.0                                             
                   Server : pg-crm-4743                                       
                     Port : 8282                                              
               Start time : 2026-01-29 18:06:43                               
          Collection rate : low                                               
   Table monitoring limit : 1000                                              
   Query monitoring limit : 30000                                             
     Use postgres queryid : on                                                
             Sql max size : 256000                                            

               Proxy
                     host :                                                   
                     port : 0                                                 
                     user :                                                   
                 password :                                                   

              Upload
                     host : demo.datasentinel.io                              
                     port : 443                                               

         Connections
                 declared : 1                                                 
                  running : 1                                                 
              not running : 0                 
```

{% endcode %}

## **Upload Server**

> The Upload Server refers to the server name of the platform where metrics are transmitted.

### Set

* Change the server where metrics are sent

```bash
datasentinel set server app.datasentinel.io 443
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Server successfully set!


        Server
                host : app.datasentinel.io
                port : 443
```

{% endcode %}

### Show

> Show the platform server where metrics are sent

```bash
datasentinel show server
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

        Server
                host : app.datasentinel.io
                port : 443
```

{% endcode %}

### Test

```bash
datasentinel test server
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

TEST: The upload server is reachable and up!


        Server
                host : app.datasentinel.io
                port : 443
```

{% endcode %}

## **Token**

### Set

> Configure the authentication token used to access the platform.\
> This should only be done during initialization. The agent subsequently retrieves updated tokens from the platform.

```bash
datasentinel set token <token value>
```

{% code title="Response" %}

```
Copyright 2026 (c) Datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Token successfully set!


          Server
                  host : app.datasentinel.io
                  port : 443
```

{% endcode %}

### Show

> After testing the token on the platform's upload server, the validity date of the token is provided.

```bash
datasentinel show token
```

{% code title="Response" %}

```
Copyright 2026 (c) Datasentinel- All rights reserved        www.datasentinel.io
================================================================================

                    Token : <token value>

            Organization : ds-data
          Expiration Date : 2023-07-22 18:09:29
```

{% endcode %}

## **Proxy**

> Under certain circumstances, an intermediary proxy server is required to establish a connection between the agent and the platform server.

### Set

* create a json file with proxy settings and update the agent

{% code title="JSON description" %}

```bash
cat > proxy.json << EOF
{
    "host": "myProxyHostName",
    "port": 4587,
    "user": "username (optional)",
    "password": "value (optional)"
}
EOF
```

{% endcode %}

```bash
datasentinel set proxy -f proxy.json
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Proxy successfully set!


          Proxy
                host : myProxyHostName
                port : 4587
                user :
            password :
```

{% endcode %}

### Show

```bash
datasentinel show proxy
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

          Proxy
                host : hostname
                port : 4587
                user :
            password :
```

{% endcode %}

### Delete

```bash
datasentinel delete proxy
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Proxy successfully deleted!


          Proxy
                host :
                port : 0
                user :
            password :
```

{% endcode %}

## **Connections**

### Show

```bash
datasentinel show connections
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

name                 status     state      host                 port   user
--------------------------------------------------------------------------------
:9342                enabled    running    pg-sales-1734          9342 datasentinel
  tags : application=sales,environment=production,provider=amazon,datacenter=lyon
```

{% endcode %}

### Enable All

```bash
datasentinel enable all
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Connections enabled!


name                 status     state      host                 port   user
--------------------------------------------------------------------------------
:9342                enabled    running    pg-sales-1734          9342 datasentinel
  tags : application=sales,environment=production,provider=amazon,datacenter=lyon
```

{% endcode %}

### Disable All

```bash
datasentinel disable all
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Connections disabled!


name                 status     state      host                 port   user
--------------------------------------------------------------------------------
:9342                disabled   not running pg-sales-1734          9342 datasentinel
  tags : application=sales,environment=production,provider=amazon,datacenter=lyon
```

{% endcode %}

## **Connection**

### Add

* Create a JSON file with connection settings

{% code title="JSON" %}

```bash
cat > newConnection.json << EOF
{
    "host": "pg-sales-1734",
    "port": 9342,
    "user": "datasentinel",
    "password": "sentinel",
    "tags": "application=sales,environment=production,provider=amazon,datacenter=lyon",
}
EOF
```

{% endcode %}

```bash
datasentinel add connection myNewConnection -f newConnection.json
```

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Connection added!


                   Name : myNewConnection
                 Status : enabled
                  State : connected

                   Host : pg-sales-1734
                   Port : 9342

                   user : datasentinel
               password : sentinel

        Lock monitoring : on
  Lock monitoring delay : 30s
       Table monitoring : on

          Query samples : off

       Query monitoring : on
               Optimize : on
              Min calls : 2
               Min time : 1s
               
   Use postgres queryid : off                                               

                   tags : application=sales,environment=production,provider=amazon,datacenter=lyon
```

{% endcode %}

### Show

```bash
datasentinel show connection myNewConnection
```

* Parameter

  > The connection name

{% code title="Response" %}

```
Copyright 2026 (c) Datasentinel- All rights reserved        www.datasentinel.io
================================================================================

                     Name : myNewConnection                                            
                   Status : enabled                                           
                    State : connected                                         

                     Host : pg-crm-4743                                       
                     Port : 9342                                              

                     user : datasentinel                                      
                 password : sentinel                                          

          Lock monitoring : on                                                
    Lock monitoring delay : 30s                                               
         Table monitoring : on                                                

            Query samples : off                                               

         Query monitoring : on                                                
                 Optimize : off                                               
                Min calls : 2                                                 
                 Min time : 1s                                                

     Use postgres queryid : off                                               

                     tags : application=crm,environment=production,provider=on-premises,datacenter=paris
```

{% endcode %}

### Dump

> Dump connection properties in JSON format

```bash
datasentinel dump connection myNewConnection
```

* Parameter

  > The connection name

{% code title="Response" %}

```json
{
    "name": "myNewConnection",
    "host": "pg-sales-1734",
    "port": 9342,
    "user": "datasentinel",
    "password": "sentinel",
    "tags": "application=sales,environment=production,provider=amazon,datacenter=lyon ",
    "enabled": true,
    "connected": true,
    "collection-rate": "low",
    "samples": false,
    "lock-monitoring": true,
    "lock-monitoring-delay": 30,
    "table-monitoring": true,
    "query-monitoring": true,
    "query-monitoring-optimize": true,
    "query-monitoring-min-calls": 2,
    "query-monitoring-min-time": 1,
    "use-postgres-queryid": false,
}
```

{% endcode %}

### Delete

```bash
datasentinel delete connection myNewConnection
```

* Parameter

  > The connection name

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Connection successfully deleted!
```

{% endcode %}

### Enable

> Activate the connection and initiate connection attempts in order to start monitoring

```bash
datasentinel enable connection myNewConnection
```

* Parameter

  > The connection name

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Connection enabled!


                  Name : myNewConnection
                Status : enabled
                State : connected

                  Host : pg-sales-1734
                  Port : 9342

                  user : datasentinel
              password : sentinel

      Lock monitoring : on
Lock monitoring delay : 30s
      Table monitoring : on

        Query samples : off

      Query monitoring : on
              Optimize : on
            Min calls : 2
              Min time : 1s

                  tags : application=sales,environment=production,provider=amazon,datacenter=lyon
```

{% endcode %}

### Disable

```bash
datasentinel disable connection myNewConnection
```

* Parameter

  > The connection name

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Connection disabled!


                  Name : myNewConnection
                Status : enabled
                State : connected

                  Host : pg-sales-1734
                  Port : 9342

                  user : datasentinel
              password : sentinel

      Lock monitoring : on
Lock monitoring delay : 30s
      Table monitoring : on

        Query samples : off

      Query monitoring : on
              Optimize : on
            Min calls : 2
              Min time : 1s

                  tags : application=sales,environment=production,provider=amazon,datacenter=lyon
```

{% endcode %}

### Update

```bash
cat > updateConnection.json << EOF
{
    "host": "pg-sales-1734",
    "port": 9342,
    "user": "datasentinel",
    "password": "sentinel",
    "tags": "application=sales,environment=production,provider=microsoft,datacenter=paris",
}
EOF
```

```bash
datasentinel update connection myNewConnection -f updateConnection.json
```

* Parameter

  > The connection name

{% code title="Response" %}

```
Copyright 2026 (c) datasentinel- All rights reserved        www.datasentinel.io
================================================================================

Connection updated!


                    Name : myNewConnection
                  Status : enabled
                  State : connected

                    Host : pg-sales-1734
                    Port : 9342

                    user : datasentinel
                password : sentinel

        Lock monitoring : on
  Lock monitoring delay : 30s
        Table monitoring : on

          Query samples : off

        Query monitoring : on
                Optimize : on
              Min calls : 2
                Min time : 1s

                    tags : application=sales,environment=production,provider=amazon,datacenter=lyon
```

{% endcode %}

## **Collection Level**

> The Agent Version 3.2 introduces the [Collection Level](/manual/implementation/agent-usage/collection-level.md) feature, which was released in February 2023 and allows you to choose the metrics to monitor.

### Query Samples

```bash
datasentinel update connection ":9342" samples on|off
```

* Parameter

  > The connection name

### Lock Monitoring

```bash
datasentinel update connection ":9342" lock-monitoring on|off
```

* Parameter

  > The connection name

### Lock Monitoring Delay

```bash
datasentinel update connection ":9342" lock-monitoring-delay <seconds>
```

* Parameters

  > The connection name\
  > Seconds

### Table Monitoring

```bash
datasentinel update connection ":9342" table-monitoring on|off
```

* Parameter

  > The connection name

### Query Monitoring

```bash
datasentinel update connection ":9342" query-monitoring on|off
```

* Parameter

  > The connection name

### Query Monitoring Optimize

```bash
datasentinel update connection ":9342" query-monitoring-optimize on|off
```

* Parameter

  > The connection name

### Query Monitoring Min Calls

```bash
datasentinel update connection ":9342" query-monitoring-min-calls <value>
```

* Parameters

  > The connection name\
  > Minimum number of calls registered in **pg\_stat\_statements**

### Query Monitoring Min Time

```bash
datasentinel update connection ":9342" query-monitoring-min-time <seconds>
```

* Parameter

  > The connection name\
  > Minimum total execution time (seconds)

## **Internals**

> Since Agent Version 3.2

### Show Metrics

> Displays internal metrics and caches for debugging purposes

```bash
datasentinel show metrics
```

{% code title="JSON output" %}

```json
{
  "version": "3.9.0",
  "port": 8282,
  "start_time": "2026-01-31 13:08:27",
  "memory": "59MB",
  "threads": 18,
  "pg_connections": 2,
  "running": 1,
  "not_running": 1,
  "connections": [
    {
      "name": "test",
      "stat_statements": 0,
      "stat_statements_cache": 0,
      "stat_plans_cache": 0,
      "query_ids_cache": 0,
      "missing_query_ids": 0,
      "plan_ids_cache": 0,
      "cache_tables": 0,
      "table_stats_cache": 0,
      "index_stats_cache": 0,
      "normal_task_runtime": 0,
      "low_task_runtime": 0,
      "tables_monitoring_limit": 2500,
      "query_monitoring": true,
      "query_monitoring_limit": 35000,
      "query_monitoring_min_calls": 2,
      "query_monitoring_min_time": 1,
      "query_monitoring_optimize": true,
      "xa_trans_optimized": 0,
      "insert_values_optimized": 0,
      "in_list_query_optimized": 0,
      "execution_plan_optimized": 0,
      "samples": false,
      "lock_monitoring": true,
      "lock_monitoring_delay": 10,
      "pool_used": 0
    },
    {
      "name": "test_connection",
      "stat_statements": 109,
      "stat_statements_cache": 109,
      "stat_plans_cache": 52,
      "query_ids_cache": 51,
      "missing_query_ids": 0,
      "plan_ids_cache": 48,
      "cache_tables": 1,
      "table_stats_cache": 148,
      "index_stats_cache": 352,
      "normal_task_runtime": 1663,
      "low_task_runtime": 12069,
      "tables_monitoring_limit": 2500,
      "query_monitoring": true,
      "query_monitoring_limit": 35000,
      "query_monitoring_min_calls": 21,
      "query_monitoring_min_time": 33,
      "query_monitoring_optimize": true,
      "xa_trans_optimized": 0,
      "insert_values_optimized": 23,
      "in_list_query_optimized": 1,
      "execution_plan_optimized": 0,
      "samples": true,
      "lock_monitoring": true,
      "lock_monitoring_delay": 10,
      "pool_used": 3
    }
  ]
}
```

{% endcode %}

### Test Query Monitoring Optimization

> The Query Optimize feature fetches queries from **pg\_stat\_statements**, filtered by minimum calls or minimum total execution time, groups similar queries, and shows the optimization gain at each level.

```bash
datasentinel update connection ":9342" test-query-monitoring-optimize
```

* Parameter

  > The connection name

{% code title="JSON output" %}

```json
{
  "pg_stat_statements": 964,
  "min_calls_filter": 21,
  "min_time_filter": "33s",
  "filtered_statements_get_time": "153ms",
  "filtered_statements_with_min_calls_or_min_time": 109,
  "filtered_ratio": "89%",
  "optimized_statements": 109,
  "optimized_ratio": "0%",
  "optimized_statements_run_time": "8ms"
}
```

{% endcode %}


---

# 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://docs.datasentinel.io/manual/implementation/agent-usage/cli.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.