All Products
Search

This Product

    Tablestore:Command-line tool

    Document Center

    Tablestore:Command-line tool

    Last Updated:Sep 24, 2026

    tablestore-agent-cli is the command-line tool released by the Knowledge and Memory Storage Service. It supports managing and operating knowledge bases and memory stores, and is suitable for development debugging, operations, and data governance scenarios.

    Quick start

    Download and install the command-line tool, configure your access credentials, and you are ready to manage knowledge base and memory store resources.

    Installation

    The command-line tool is published to the npm registry. Install it globally with npm.

    Prerequisites: Node.js 18 or later.

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

    npm package URL: https://www.npmjs.com/package/@tablestore/tablestore-agent-cli.

    Dashboard

    The command-line tool includes a built-in Next.js-based web Dashboard that provides configuration features and a visual management and retrieval debugging interface for knowledge bases and memory stores.

    Start the Dashboard

    tablestore-agent-cli dashboard start                     # Default: listens on 127.0.0.1:3000
tablestore-agent-cli dashboard start -p 9999             # Custom port
tablestore-agent-cli dashboard start --host 0.0.0.0      # Custom bind address

    After it starts, open the corresponding address in your browser.

    Memory store scope selection rules

    When you enter a specific memory store in the Dashboard, the default scope is */*/*/*. In this case, only list all long-term memories and request audit operations are supported.

    To perform memory retrieval, you must specify AppId and TenantId. AgentId and RunId can be set to specific values or use the wildcard *.

    To add a new memory, you must specify the full scope (all of AppId, TenantId, AgentId, and RunId must be specific values).

    Configure access credentials

    If you do not use the Dashboard, you can manually configure access credentials and verify connectivity.

    Required configuration

    Configure the AccessKey ID and AccessKey Secret of your Alibaba Cloud account. For information about how to obtain an AccessKey, see Create an AccessKey.

    tablestore-agent-cli configure set access_key_id 'LTAI5t...'
tablestore-agent-cli configure set access_key_secret 'xxx'

    Optional configuration

    Configure the following items as needed based on your use case.

    Tablestore instance

    tablestore-agent-cli configure set ots_endpoint 'https://xxx.cn-beijing.ots.aliyuncs.com'
tablestore-agent-cli configure set ots_instance_name 'xxx'

    If you do not configure a Tablestore instance, the command-line tool automatically creates a managed instance in the China (Beijing) region and accesses it over the public endpoint. The automatic creation process may take up to 30 seconds. To specify a region, configure region:

    tablestore-agent-cli configure set region 'cn-beijing'

    OSS bucket

    The OSS bucket configuration is required only for the document upload feature of knowledge bases.

    Note

    The knowledge base needs read and write permissions for the OSS bucket. Grant the permissions with a single click via the following link: Authorize Tablestore to read and write OSS.

    tablestore-agent-cli configure set oss_endpoint 'https://oss-cn-hangzhou.aliyuncs.com'
tablestore-agent-cli configure set oss_bucket_name 'my-bucket'

    Default memory store scope

    tablestore-agent-cli configure set memory_store_name 'agent_memory'
tablestore-agent-cli configure set memory_app_id 'app-001'
tablestore-agent-cli configure set memory_tenant_id 'tenant-001'
tablestore-agent-cli configure set memory_agent_id 'agent-001'
tablestore-agent-cli configure set memory_run_id 'run-001'

    After you configure a default scope, memory store commands can omit the corresponding parameters.

    Verify connectivity

    Run the doctor command to check the configuration and connectivity.

    tablestore-agent-cli doctor          # Full diagnosis
tablestore-agent-cli doctor kb       # Knowledge base only
tablestore-agent-cli doctor memory   # Memory store only

    Each check result is pass / warn / fail / skip. The exit code is 0 when all checks pass, and 1 when any check fails.

    doctor automatically creates and reuses a managed Tablestore instance and OSS bucket when needed. For more information, see Managed instance auto-creation.

    Examples

    After you complete the installation and configuration, use the following examples to quickly try the core capabilities of knowledge bases and memory stores.

    Knowledge base example: create a knowledge base and upload documents

    # Create a knowledge base
tablestore-agent-cli kb create --name my_kb --description "Product documentation knowledge base"

# Add a local document
tablestore-agent-cli kb doc-add --kb my_kb --file ./report.pdf

# Semantic retrieval
tablestore-agent-cli kb retrieve --kb my_kb --query "System architecture design"

    Memory store example: write and retrieve memories

    # Create a memory store
tablestore-agent-cli memory create --store agent_memory --description "Long-term memory store"

# Write a memory entry
tablestore-agent-cli memory add --store agent_memory --app-id app-001 --text "The user likes mapo tofu"

# Retrieve memories
tablestore-agent-cli memory search --store agent_memory --app-id app-001 --tenant-id tenant-001 --query "What food does the user like" --top-k 5

    Advanced configuration

    Configuration file location

    ~/.config/tablestore-agent-cli/config.toml. The file permission is automatically set to 0600.

    Environment variables

    Environment variables take precedence over the configuration file.

    Environment variable

    Corresponding configuration item

    TABLESTORE_ACCESS_KEY_ID

    access_key_id

    TABLESTORE_ACCESS_KEY_SECRET

    access_key_secret

    TABLESTORE_ENDPOINT

    ots_endpoint

    TABLESTORE_INSTANCE_NAME

    ots_instance_name

    TABLESTORE_OSS_ENDPOINT

    oss_endpoint

    TABLESTORE_OSS_BUCKET_NAME

    oss_bucket_name

    TABLESTORE_REGION

    region

    TABLESTORE_MEMORY_STORE_NAME

    memory_store_name

    TABLESTORE_MEMORY_APP_ID

    memory_app_id

    TABLESTORE_MEMORY_TENANT_ID

    memory_tenant_id

    TABLESTORE_MEMORY_AGENT_ID

    memory_agent_id

    TABLESTORE_MEMORY_RUN_ID

    memory_run_id

    Managed instance auto-creation

    If you do not configure ots_endpoint and ots_instance_name, the command-line tool automatically creates and reuses a managed Tablestore instance during doctor or actual operations. The creation process may take up to 30 seconds. The result is written to the [managed_ots] section of the configuration file and reused by subsequent commands. After you manually set an explicit target, the managed cache is automatically cleared.

    The same applies to the OSS bucket. It is automatically created on demand during upload operations such as doctor kb or kb doc-add, and cached in the [managed_oss] section of the configuration file.

    Multi-instance management

    You can save multiple named instances in the same configuration file and quickly switch between them using the command line or the switcher at the top of the Dashboard.

    # Configure an AccessKey for a specific instance
tablestore-agent-cli configure set --instance prod access_key_id 'LTAI...'

# Switch the active instance
tablestore-agent-cli configure use prod

# View the current configuration
tablestore-agent-cli configure show

    This is useful for quickly switching between multiple environments such as production, staging, and testing.