Get started with tablestore-agent-cli and Agent Skill - Tablestore - Tablestore

Prerequisites

A Tablestore instance. For supported regions, see Quick start.
OSS authorization (read and write permissions on OSS buckets).
An AccessKey ID and AccessKey Secret.

CLI and Skill overview

tablestore-agent-cli is the command-line tool for managing knowledge stores. All commands return structured JSON that agents can parse directly. tablestore-agent-knowledge is the companion Agent Skill package that lets agents perform knowledge store operations from natural language.

Global parameter	Description
`-q`	Strip the response envelope (`code` / `message` / `requestId`) and return only the payload, reducing token overhead.
`-y`	Skip confirmation prompts. Useful for scripts and CI pipelines.
`--instance`	Specify the instance name. Defaults to the `default` instance if omitted.
`--timeout`	Set the command timeout. Defaults to 30 seconds.

Installation and configuration

Install the CLI

The CLI requires Node.js 18 or later. Run the following command to install:

npm install -g @tablestore/tablestore-agent-cli --registry=https://registry.npmjs.org/

Verify the installation:

tablestore-agent-cli --version

Configure credentials

Manually configure only the region, AccessKey, and Tablestore instance settings. The OSS endpoint and bucket are derived automatically from the region when you first run an OSS operation.

tablestore-agent-cli configure set region cn-hangzhou
tablestore-agent-cli configure set access_key_id <AccessKey ID>
tablestore-agent-cli configure set access_key_secret <AccessKey Secret>
tablestore-agent-cli configure set ots_endpoint https://<instance-name>.cn-hangzhou.ots.aliyuncs.com
tablestore-agent-cli configure set ots_instance_name <instance-name>

After configuration, run a connectivity check:

tablestore-agent-cli doctor

All items showing status=pass indicate that the configuration is ready.

Connect an agent framework

Any agent that supports Skills or CLI invocation (such as OpenClaw, Hermes, QoderWork, CherryStudio, or Claude Code) can access the knowledge store with the same Skill package and credentials. Integration takes three steps:

Install the Skill (point the agent to the Skill package URL).
Configure credentials (manually run configure set or import via token).
Operate the knowledge store with natural language.

Install the Skill

Enter the following instruction in the agent conversation. The agent learns the Skill and installs the CLI automatically:

Please learn the skill at https://tablestore-doc.oss-cn-hangzhou.aliyuncs.com/aliyun-tablestore-ai/agent-storage/tablestore-agent-knowledge.zip and install the CLI.

Configuration

Configure the AccessKey directly with the configure set command to avoid exposing sensitive credentials in the agent conversation. The agent can assist with region and instance settings.

After you configure the region, AccessKey ID, and AccessKey Secret, the CLI automatically configures the OSS bucket and connects to the Tablestore instance on first use.

Usage example

After configuration, operate the knowledge store with natural language in the conversation:

Create a knowledge store called project_wiki and upload the documents in ./docs.
Search project_wiki for content about the deployment process.

The agent translates natural language into CLI commands that cover knowledge store management, document management, chunk management, and retrieval.

Share a knowledge store across devices

After configuring the source device, export a token and import it on the target device to access the same knowledge store from multiple endpoints.

Export a token

Run tablestore-agent-cli configure export on the source device:

tablestore-agent-cli configure export

The output is in the following format:

instance=<instance-name> token=tablestore_agent_storage://eyJ2IjoyLC...

Import a token

Run the following command on the target device:

tablestore-agent-cli configure import --name <instance-name> <token>

After you import the token, use the --instance global parameter to access the knowledge store on that instance:

tablestore-agent-cli --instance <instance-name> -q kb retrieve --kb product_docs --query "deployment process"

Alternatively, send the token directly to the target agent and let it perform the import:

My token is tablestore_agent_storage://eyJ2IjoyLC.... Please import the knowledge store configuration.

Dashboard

The CLI includes a built-in visual dashboard. Start it with a single command:

tablestore-agent-cli dashboard start

The dashboard helps you manage and debug knowledge stores and memory stores. Key capabilities:

Adjust retrieval parameters and index configurations (searchType, top-k, rerank strategy).
Verify end-to-end retrieval results.
Mount and switch between multiple knowledge stores for comparative testing.
Chat with an LLM and observe Q&A performance after retrieval results are injected.

Usage notes

Do not pass credentials in plain text within agent conversations. Configure the AccessKey with the configure set command directly.
The configure export command outputs a token that encodes all credentials, including the AccessKey. Transfer tokens through a secure channel (such as a password manager) and do not expose them publicly.
Instance names support only letters, digits, and hyphens.
After you upload a document, the system parses and vectorizes the content asynchronously. Use kb doc-list to check document status and wait until status is completed before running retrieval.

Tablestore:Get started with CLI and Agent Skill