idmp-cli

简体中文

idmp-cli is the command-line interface for TDengine IDMP. It is designed for three use cases:

• daily operator workflows such as login, profile switching, and readonly queries
• scripted or CI-driven API execution with explicit risk controls
• AI-agent workflows: use the Claude Code plugin for local Claude Code, or install skills separately for other agents

Replace sample URLs, usernames, passwords, and API keys with your own values.

Installation

Install the published npm package:

npm install -g @tdengine/idmp-cli

This installs the CLI only. It does not install the Claude Code plugin.

Verify that the binary is available:

idmp-cli --help
idmp-cli --version

idmp-cli --version prints the build version string. It is command output, not a separate command. Typical output looks like:

idmp-cli version <version>

Some builds also append a short git hash in parentheses when that metadata is embedded at build time.

Offline installation from a release bundle

If you are working in an offline or controlled environment, use the installer included in an extracted release bundle:

bash installers/install-cli-offline.sh

The offline installer can also take --asset-root <path> when the extracted bundle is not in the default location.

Skills and Claude Code plugin

idmp-cli works on its own. For agent-driven workflows, choose the installation path that matches the agent runtime:

• Claude Code: install the TDengine Claude Code plugin only. The plugin already bundles the matching skills, so you do not need to install the same skills again into Claude Code.
• Other agents: install taosdata/agent-skills separately so the agent can classify tasks, discover command paths, and follow the intended safety workflow.

Install TDengine skills online for other agents

Preview the repository first:

npx --yes skills add taosdata/agent-skills -g -y --list

Install the skills globally:

npx --yes skills add taosdata/agent-skills -g -y

Install the Claude Code plugin online

Online installation goes through the Claude Code plugin marketplace, not through npm or a repository installer script.

First add the TaosData marketplace:

claude plugin marketplace add taosdata/agent-skills

Then install idmp-plugin:

claude plugin install idmp-plugin@taosdata

These names are fixed:

• marketplace source: taosdata/agent-skills
• marketplace: taosdata
• plugin: idmp-plugin

Install the offline Claude Code plugin

The release bundle contains both an extracted Claude Code plugin and a separate offline skills payload. For local Claude Code, install the plugin first; it already includes the matching skills.

Install the offline Claude Code plugin:

bash installers/install-plugin-offline.sh

Both the online and offline installers use the same default plugin directory:

~/.claude/plugins/idmp-plugin

Launch Claude Code with that plugin directory:

claude --plugin-dir "$HOME/.claude/plugins/idmp-plugin"

Install offline skills for other agents

If you are using an agent other than Claude Code, install the offline skills bundle separately:

bash installers/install-skills-offline.sh

Both offline installers support:

• --force to replace an existing installation explicitly
• --target-dir <path> to install into a non-default directory
• --asset-root <path> to point at a custom extracted bundle location

Recommended workflow with agents

1. Let the skill identify the task category first.
2. Use idmp-cli schema search <keyword> to locate the correct command path.
3. Inspect the generated schema before executing an unfamiliar command.
4. Use --dry-run first for write operations whenever the command supports it.

Quick start

Initialize a profile and log in

A profile stores the server URL and your default identity. For most operators, starting with default is enough.

Log in with username and password without exposing secrets in shell history:

printf '%s\n' "$IDMP_PASSWORD" | idmp-cli config init \
  --profile default \
  --server http://your-idmp.example.com:6042 \
  --username [email protected] \
  --password-stdin

Log in with a pre-issued API key:

printf '%s\n' "$IDMP_API_KEY" | idmp-cli config init \
  --profile default \
  --server http://your-idmp.example.com:6042 \
  --api-key-stdin

config init can create or update the profile, authenticate immediately, and persist the session in one step.

Validate the local setup

idmp-cli profile list
idmp-cli auth check
idmp-cli doctor --offline

doctor --offline verifies local configuration, session storage, and generated metadata without touching the network.

Discover the right command before calling the API

Search the generated schema:

idmp-cli schema search elements

Inspect the matching command path:

idmp-cli schema element.elements.list
idmp-cli element elements list --help

Run a readonly query:

idmp-cli element elements list --params '{"current":1,"size":20}' --format table

Call a raw endpoint when you already know the path:

idmp-cli api GET /api/v1/elements --params '{"current":1,"size":20}'

Switch to another saved environment temporarily:

idmp-cli --profile staging auth check --remote

Command reference

The CLI has two layers:

• a small set of operator-oriented commands such as auth, config, profile, schema, api, and doctor
• many generated service commands derived from the OpenAPI registry, such as element, analysis, dashboard, and user

Global flags

These flags are available on the root command and most subcommands:

| Flag | Purpose | | --- | --- | | --profile <name> | Use a specific saved profile instead of the active default. | | --debug-http | Emit structured HTTP request and response traces to stderr. | | --request-id <id> | Attach a request identifier to API calls and debug traces. | | --max-response-size <size> | Cap response body size; supports suffixes such as k, m, and g. | | --help | Show command help. | | --version | Print the CLI version. |

High-frequency parameter patterns

The CLI reuses a small number of parameter styles across commands:

| Pattern | Where it appears | Recommended usage | | --- | --- | --- | | --password-stdin | config init, auth login | Preferred way to pass passwords from scripts or CI. | | --api-key-stdin | config init, auth login | Preferred way to pass API keys without exposing them in shell history. | | --server <url> | config init, profile add, config set-server | Set or replace the target IDMP server URL. | | --username <value> | config init, auth login, profile add | Set the default or current login identity. | | --params '<json>' | generated readonly commands, api | Pass query parameters as a JSON object. | | --data '<json>' | mutating generated commands, api | Pass the request body as JSON. | | --format table\|json\|pretty\|csv\|ndjson | api, generated commands | Control how results are printed. | | --page-all | paginated GET commands, api | Fetch and merge all pages for current/size-style pagination. | | --page-limit <n> | paginated GET commands, api | Cap the number of merged rows when using --page-all. | | --page-delay <duration> | paginated GET commands, api | Add a delay between page requests. | | --dry-run | mutating commands, api, profile removal | Preview the request or local change without executing it. | | --ack-risk | mutating commands, api, profile removal | Required acknowledgment for non-readonly operations. | | --offline | doctor | Skip remote checks and verify local state only. | | --limit <n> | schema search | Limit the number of search matches returned. |

Core command groups

| Command | Purpose | Common subcommands and usage | | --- | --- | --- | | auth | Manage authentication state. | auth login, auth logout, auth check, auth status, auth list, auth whoami | | config | Create, update, inspect, or remove profile configuration. | config init, config show, config remove, config set-server | | profile | Manage named environments. | profile add, profile list, profile rename, profile use, profile remove | | schema | Inspect generated command schemas and search paths. | schema, schema search <keyword>, schema <service.resource.method> | | api | Call a raw IDMP API path directly. | api GET /path --params '{...}', api POST /path --data '{...}' --dry-run | | doctor | Run health checks for config, auth, connectivity, and metadata. | doctor, doctor --offline | | completion | Generate shell completion scripts. | completion <shell> | | help | Show help for any command group. | help, <command> --help |

Authentication and profile commands

| Command | Purpose | Notes | | --- | --- | --- | | idmp-cli auth login | Log in with username/password or API key. | On a TTY, missing secrets are prompted interactively. For automation, prefer --password-stdin or --api-key-stdin. | | idmp-cli auth check | Verify current authentication state. | Add --remote to validate the token by calling whoami. | | idmp-cli auth status | Show local authentication status. | Useful for a quick local check without implying a remote verification. | | idmp-cli auth list | List profiles and their local auth state. | Good for multi-profile environments. | | idmp-cli auth whoami | Show current user information. | Requires a valid session or token. | | idmp-cli config init | Create or update a profile and optionally authenticate immediately. | Supports --profile, --server, --username, --force, --password-stdin, and --api-key-stdin. | | idmp-cli config show | Show the active configuration. | Works with --profile <name> to inspect another profile. | | idmp-cli config remove | Remove a saved profile. | Supports --dry-run and --ack-risk. | | idmp-cli profile add <name> | Add a profile without authenticating yet. | Use --server and --username to seed the profile. | | idmp-cli profile use <name> | Switch the active profile. | A convenient operator command for shared terminals. | | idmp-cli profile rename <old> <new> | Rename a profile. | Keeps profile management explicit and local. | | idmp-cli profile remove <name> | Remove a profile. | Supports --dry-run and --ack-risk. |

Generated service command groups

The following top-level commands are generated from IDMP service metadata. They all follow the same structure:

idmp-cli <service> <resource> <method> [flags]

Use idmp-cli schema search <keyword> to discover the exact path before calling one of them.

Proxy-only surfaces such as MCP are intentionally not exposed as dedicated top-level commands. If you need to hit a proxy endpoint, use the raw API surface instead, for example idmp-cli api GET /api/v1/mcp/....

| Command | Purpose | | --- | --- | | ai | AI chat service commands. | | analysis | Analysis management commands. | | analysis-template | Analysis template management commands. | | annotation | Element annotation commands. | | attr-template | Attribute template management commands. | | attribute | Attribute management commands. | | category | Category management commands. | | dashboard | Dashboard management commands. | | dashboard-template | Dashboard template management commands. | | data | Import and export data management commands. | | datasource | Datasource management commands. | | document | Element document management commands. | | download | File download commands. | | element | Element management commands. | | enumeration | Enumeration management commands. | | event | Event management commands. | | event-source | Event source resource commands. | | event-template | Event template management commands. | | expression | Expression and related element commands. | | file | File management commands. | | initialization | TDasset initialization commands. | | internal | Internal service commands. | | metric | Composite metric management commands. | | metrics | Observability metrics commands. | | notification | Notification rule management commands. | | panel | Panel management commands. | | panel-template | Panel template management commands. | | permission | Permission management commands. | | role | Role management commands. | | sample | Sample management commands. | | share | Share management commands. | | sync-meta | Metadata synchronization commands. | | system | License and system management commands. | | task | Task management commands. | | template | Element template management commands. | | uom | Unit-of-measure management commands. | | user | User management commands. |

Safe usage recommendations

Use these practices by default:

• prefer --password-stdin and --api-key-stdin over inline secrets
• inspect schema output before using a command you have not used before
• use --dry-run before non-readonly operations whenever available
• only pass --ack-risk when you are intentionally applying a change
• keep separate profiles for default, staging, and prod
• use --request-id for traceability in logs and support workflows

Troubleshooting

idmp-cli: command not found

• confirm that the global npm bin directory is on PATH
• reopen the terminal after npm install -g

Authentication works in the UI but not in the CLI

• rerun idmp-cli config init and verify the server URL
• confirm that the password or API key is still valid
• run idmp-cli auth check --remote to verify the token remotely

You do not know which command path to use

• start with idmp-cli schema search <keyword>
• inspect the best match with idmp-cli schema <service.resource.method>
• only then call the generated command or raw api path

Agent workflows are guessing the wrong command

• when you use Claude Code, install only the TDengine Claude Code plugin
• when you use another agent, install taosdata/agent-skills separately
• instruct the agent to search schema first instead of guessing

Development, test, and release

Build from source

From idmp-cli/:

make generate-openapi
make build
./idmp-cli --version

Inspect the npm package contents:

npm pack --dry-run

Local verification

Fast smoke pass:

make smoke

Main local verification flow:

make unit-test
make skills-test
make cli-e2e-test
make race-test
make coverage-test
npm pack --dry-run

Run the full suite:

make full

Test reports are written under tests/reports/.

Skill-oriented coverage

This project is often used through agents rather than hand-written shell commands, so skill-oriented coverage matters.

Useful references:

• tests/skills/AI_AGENT_NATURAL_LANGUAGE_CASES.md
• tests/skills/
• tests/e2e/

When you add or change a command:

1. update generated metadata if required
2. add or adjust direct CLI coverage
3. add or adjust agent-facing natural-language coverage when the command is meant to be skill-driven

Release assets

Generate local release artifacts:

npm run release:generate

For macOS signing and notarization, the release workflow expects environment variables such as:

export SIGN_MACOS_BINARIES=1
export NOTARIZE_MACOS_BINARIES=1
export APPLE_SIGN_IDENTITY="Developer ID Application: <certificate-common-name> (<team-id>)"
export APPLE_KEYCHAIN_PATH="$RUNNER_TEMP/app-signing.keychain-db"
export APPLE_KEYCHAIN_PASSWORD="<keychain-password>"
export APPLE_NOTARY_KEY_ID="<notary-key-id>"
export APPLE_NOTARY_ISSUER="<notary-issuer>"
export APPLE_NOTARY_KEY="<notary-private-key>"
export APPLE_NOTARY_TEAM_ID="<team-id>"

Do not hardcode real identities, private keys, or team information into documentation or scripts.

npm publishing

Dry run:

npm run release:publish:dry-run

Actual publish:

npm run release:publish