Traditional data connectors such as JDBC and ODBC are great standards for interacting with databases, but they can only do so through predefined paths, leaving intelligence to human users. However, with the proliferation of agents, particularly Data Agents, intelligence is shifting from human-initiated action to automatic reasoning by agents capable of handling non-deterministic inputs and acting flexibly.
This paradigm shift has created opportunities to offload many best practices and knowledge from humans onto AI. However, to accomplish this, a natural-language interface with Agents is needed, and that is where a Command Line Interface (CLI) is ideal. Paired with skills that contain the best practices and knowledge, and a data agent can start to take on more and more complicated tasks.
For the reason above, we are excited to announce that VeloDB is releasing VeloCLI, a CLI that gives developers and agents the exact database and cloud facts they need, straight from the terminal. Enabling agents to tackle the most complicated database operations
1. What VeloCLI Provides
VeloCLI provides the following characteristics that help agents work with data
Stable commands: The CLI uses composable, predictable verbs like sql, tablet, profile, and cloud. The agent learns these once and reuses them on every run. The commands keep their shape and never surprise the AI, so it can chain operations together with agent skills without relearning the tool.
Compact responses: Every command takes the same short path: execute, filter, format, return. The tool shrinks a page-long text profile to a handful of numbers, summarizes sprawling tablet listings, and returns tidy JSON. This compression leaves room in the agent's memory to think.
A cloud that the agent can operate: VeloCLI does not stop at the database. It lets the agent run the cloud too. Query logs, cluster metrics, and cluster status come back as plain facts that the agent can read. The agent reads the state, makes a change, and checks the result in one loop. The cloud turns into an environment the agent can understand and operate on its own.
Trustworthy facts: Results come back as clean, labeled data the agent can read as-is. When a command fails, the tool surfaces what went wrong and how to fix it, rather than throwing a vague error. The agent reasons over facts it can believe.
2. Working with VeloCLI: Diagnosing a Slow Query
When it comes to database operations, one of the most common tasks is diagnosing slow-running queries. Below is an example of a user asking, "Why is this query slow?"
The agent follows the velodb-best-practices skill, which tells it what to check and in what order. It starts by reading the table layout:
velocli tablet hits.hits --format json
{
"model": "DUPLICATE",
"sort_key": ["CounterID", "EventDate", "UserID", "EventTime", "WatchID"],
"bucket_key": ["UserID"],
"bucket_count": 48,
"replication_num": 1,
"total_size_gb": 12.58,
"total_rows": 99996670,
"health": {
"tablets": 48,
"avg_tablet_mb": 268.4,
"tablet_skew": 1.0
}
}
A tablet_skew of 1.0 means the data is balanced across all 48 tablets, so a lopsided table is not the problem. The agent crosses that off and turns to the query itself, running it with profiling switched on and pulling back the parsed result:
velocli sql "SELECT ..." --profile --format json
velocli profile get d237f96b66c64f28-ac9adef278fa6c2d
summary.total_time: 39sec279ms
time_breakdown:
plan: 17ms
schedule: 7ms
wait_fetch_result: 39sec254ms (99.9% in BE execution)
query_stats:
total_scan_rows: 81,032,111
total_peak_memory: 1,442,224,168 (1.4GB)
spilled_operators: 0
blocked_operators: 0
operators:
OLAP_SCAN_OPERATOR 30,163ms 76.8% mem=162MB
AGGREGATION_SINK 990ms 2.5% mem=1,126MB
DATA_STREAM_SINK 402ms 1.0% mem=7MB
One read tells the agent everything: 99.9% in backend execution, OLAP_SCAN_OPERATOR burning 76.8% over 81 million rows, no spilling or blocking. A scan problem, not memory or planning.
Now the agent has the full picture: the table's layout and the query's profile, both as clean facts. It applies the VeloDB best-practice rules, proposes a fix, and checks the new plan with a dry run before anyone touches production:
velocli sql "EXPLAIN <candidate>"
3. Working with VeloCLI: Cloud Operations
When it comes to managing data infrastructure, many tasks are done outside of the database, and these tasks may be sensitive as they include actions that could have detrimental effects if done improperly
These tasks involve a similar loop: read the state, make the change, confirm the result. Because each change hits live infrastructure with no human watching, VeloCLI helps the agent do it safely, with controls that do not wait for a prompt and facts to check its own work. Start with the change you reach for most: scaling up.
Here is an example for when the user asks, "Should I scale up, and if so, do it safely?" The loop opens by reading the state: the cluster's context, current size, and capacity.
# 1. Establish explicit context
velocli cloud ctx
velocli cloud use <warehouse>/<cluster>
# 2. Read current size, endpoints, and merged connection strings
velocli cloud cluster get
# 3. Gather capacity and skew facts
velocli cloud billing summary
velocli tablet hits.hits --detail
With those facts, the agent decides whether to scale. The CLI never makes that call. When it moves to make the change, two flags let it run unattended: --yes skips the interactive prompt, and --wait blocks until the resize finishes.
# 4. Apply the change, then confirm it
velocli cloud cluster resize --vcpu 16 --wait --yes
velocli cloud cluster get
That final cloud cluster get is the agent checking its own work: it reads the new size back from the cloud and confirms the change landed. The loop is closed without a human in the seat. If instead the Cloud API rejects the request, the CLI surfaces the server-side error with an actionable hint and a request ID, and the agent stops and asks you for clarification rather than guessing.
What We Learned, and How to Try It
Two requests, two different jobs: one a read-only investigation, the other a live change to production. The agent worked through both on a single principle: the CLI fetches, the agent decides. The same four properties held under each run: stable commands to chain, compact responses that fit the context window, cloud operations it could run and verify, and parsed facts to reason over instead of an opaque verdict.
Get started now by installing the tool, pointing your agent at it, and asking your hardest, slowest query question.
npm install -g @velodb/velocli
Contact the VeloDB team for more information, or join the Apache Doris community on Slack and connect with other Doris experts and users.
