CLI user guide
Reading guide
Parent section: Capability Center. Search keywords: CLI, ae-cli, command line, Coding Agent, Skill, installation, login, authorization, Capability Gateway.
- Connect from coding agents such as Codex and Claude Code: Coding Agent.
- Get a quick overview of what the CLI can do: CLI quick start.
- Connect to external services through a tool protocol: MCP.
- Capture reusable task methods: Skill.
- Set up tasks that run on a schedule: Automations.
Agentic Engine CLI (command name ae-cli) is the command-line client for Agentic Engine. It provides a stable, structured interface for both AI agents and manual use. After you install and authorize it, local AI agents such as Codex, Claude Code, and WorkBuddy can query data, build dashboards, manage tracking, and follow up on engagement and data development tasks directly, within the scope of your account permissions. You only need to describe what you want in natural language.
How it works
You ask in natural language → local AI agent (Claude Code, Codex, WorkBuddy, etc.) → ae-cli → your Agentic Engine project → verifiable results
When you install the CLI, the companion Agent Skills are installed with it. The Skills tell the AI agent which commands are available, which command to use in which scenario, and what to confirm before a write operation, so you don't need to memorize any commands.
- Permission boundary: The CLI uses exactly your account and project permissions and never gets access to any extra data. Final permissions are verified by the server.
- Credentials: Stored encrypted on your machine, separately for each Agentic Engine address. Switching environments never reuses another environment's credentials.
- Write operations: For operations that change the current state, such as creating dashboards, creating audiences, or sending pushes, have the AI propose a plan first and run it only after you confirm.
CLI vs. MCP: To let an agent use the built-in business capabilities of Agentic Engine (analytics, engagement, tracking, data development, knowledge bases, and more), use the CLI first. MCP lets an agent connect to external tools and business services; see MCP.
Prerequisites
- Agentic Engine has been upgraded to version 6.x.
- Your account has access to the target project.
- You have the Agentic Engine address: the address you normally use to open Agentic Engine in your browser, provided by your admin.
- Node.js 20 or later is installed on your machine, and the machine can access the npm registry. The first Skills installation also requires access to GitHub.
- Your machine's network can reach the Agentic Engine address.
Install and log in
Method 1: Let an AI agent install it for you (recommended)
Send the following text to an AI agent that can operate a terminal (such as Codex, Claude Code, or WorkBuddy), and replace the address in it with your Agentic Engine address:
Read https://raw.githubusercontent.com/ThinkingAIAgenticEngine/ae-cli/main/cli-installation-guide.md and follow its instructions to install or upgrade Agentic Engine CLI (ae-cli) for me. My Agentic Engine address is https://your-ae-host.example.com. Install only ae-cli and the companion Skills, and don't modify the current project. If you need me to log in and authorize, or if admin permissions are required, pause and let me know.
The AI agent completes these steps in order:
- Checks the Node.js and npm versions. If a version is too old, it uses a version manager such as nvm, fnm, or Volta to install under your user directory, and never uses
sudo npm install -g. - Installs ae-cli and the companion Skills.
- Starts the login and sends you the authorization link. After you complete authorization in your browser, it finishes logging in.
- Runs
ae-cli updateto install the CLI and Skills versions required by the current environment. - Reports the Node.js version, CLI version, Agentic Engine address, login status, and Skills sync result.
After installation, close and reopen the AI agent, or start a new task, so that it loads the newly installed Skills.
Method 2: Manual installation
First, confirm that your Node.js version is 20 or later:
node --version
If your version is too old, installing the Skills may fail with errors related to EBADENGINE or styleText. Upgrade or switch Node.js first. Then install the CLI and the companion Skills, and confirm the version:
npm install -g @thinkingai/ae-cli
npx -y skills add ThinkingAIAgenticEngine/ae-cli -g -y
ae-cli --version
If another tool on your machine already uses the command name ae-cli, check it before you replace it.
Log in and authorize
ae-cli auth login --host https://your-ae-host.example.com
ae-cli auth status --host https://your-ae-host.example.com
Login uses the device code flow: your browser opens the authorization page. Check that the verification code on the page matches the one shown in the terminal, and then click Authorize. Go back to the terminal and check the login status. If authenticated is true, you're logged in.
- If your current environment can't open a browser, add
--no-browserto the login command. - When an AI agent logs in for you, you can do it in two steps: first run the login command with
--no-waitto get the authorization link. After you complete authorization, run it again with--device-codeand the returned device code. If the device code expires, repeat the first step. - You can also copy a CLI Token from External Access in Agentic Engine, and then import it with
ae-cli auth set-token --host <address>. The input isn't echoed, and the command output never includes the token.
Sync to the required version
Each Agentic Engine environment requires a specific CLI version. After you install or upgrade, run:
ae-cli update --host https://your-ae-host.example.com
ae-cli --version
ae-cli update installs the CLI and Skills versions that the current environment requires, regardless of the latest version on npm, so don't upgrade by installing latest directly with npm. To see which version will be installed first, add --dry-run.
Starting with the 6.0.37 and 6.1.9 maintenance lines, regular commands sync automatically when they detect a version mismatch. After a successful sync, they return AE_CLI_VERSION_SYNCED; just run the original command again.
Install curated scenario Skills
ThinkingAI has distilled years of service experience into scenario Skills that cover high-frequency scenarios such as LTV analysis and anomaly diagnosis. You can have AI install them directly:
Install https://github.com/ThinkingAIAgenticEngine/scenario-skills for me
You can also install them interactively by business category in the terminal:
npx skills@latest add ThinkingAIAgenticEngine/scenario-skills
Verify readiness
Ask the AI a clear, low-risk question:
List the projects I can currently access, returning only the project name and project ID. Only view for now; don't modify anything.
If the AI recognizes Agentic Engine capabilities, prompts you to complete authorization, or returns the project list, everything is connected. If it treats the question as ordinary chat, first check whether the CLI and Skills are installed, and whether the current AI agent has reloaded the Skills.
Run your first query in 5 minutes
You don't need to learn any commands. Send this to the AI:
Show me daily active users for the last 7 days as a daily trend. First tell me which event, time range, and deduplication rule you used.
When you see the results, check just three things:
- Was the right event selected?
- Is the time range correct?
- Does it count users or occurrences?
Common scenarios
You can copy any of the prompts below directly: replace the placeholders in parentheses with real objects from your project, and then send the prompt to the AI. Prompts marked "read-only" only query data and don't modify anything. For prompts marked "run after confirmation", the AI proposes a plan first and creates or modifies anything only after you confirm.
Check core metrics (read-only)
Use this to get an overall picture of a core gameplay feature over a period of time before you decide where to dig deeper.
Show me how (core action) performed overall over the last 7 days: how many users triggered it each day and how many times in total, as a daily trend.
Confirm: which project, and which event the AI selected. If it picked the wrong event, correct it directly and it reruns the query. What to ask next: "Break down yesterday's triggering users by channel."
If the results look wrong: break the big question into smaller ones. Start with "How many users logged in each day over the last 7 days?" and add metrics after you confirm the event works.
Locate drop-off with funnels (read-only)
Show me the conversion funnel from (starting event) to (ending event) over the last 7 days:
(step 1) → (step 2) → (step 3) → (step 4),
with a 1-day conversion window, count the users and conversion rate at each step, and tell me which step has the biggest drop-off.
Confirm: the event for each funnel step (the AI lists them and waits for your confirmation), and the conversion window (usually 1 day; for campaigns, you can extend it to 3 days). If a step has 0 users, first suspect that the wrong event was selected or that there's no data in the time range.
Quick reference for common analysis models (read-only)
| Analysis type | Question it answers | Prompt to copy |
|---|---|---|
| Events Analysis | How often an action happens and how it trends | Show the daily number of users who triggered (event) and the number of times over the last 7 days, as a daily trend. |
| Funnel Analysis | Which step loses the most users | Build a funnel from (step A → step B → step C) with a 1-day window, and find the step with the biggest drop-off. |
| Retention Analysis | Whether users keep coming back | Calculate the next-day retention rate of users who did (registration) over the last 7 days, with (login) as the return event. |
| Distribution Analysis | Where users or values are concentrated | Show the user distribution of (top-up amount) over the last 7 days, grouped into ranges. |
Save as a dashboard (run after confirmation)
Build a dashboard from the (Funnel Analysis) and (Events Analysis) we just did.
First list the dashboard name, the reports it will include, and the definition of each report. Create it only after I confirm.
After the dashboard is created, the AI returns a link to it, which opens a real dashboard in Agentic Engine. Your account needs permission to create reports and dashboards.
Find causes with follow-up questions (read-only)
Real analysis usually takes several rounds of follow-up questions: change only one dimension per round, and the "to be verified" items from one round become the questions for the next. Take "revenue growth has stalled" as an example:
- Look at the big picture: "Show the number of Paying Users and logged-in users each day over the last 14 days as a daily trend, and tell me roughly what the Payment Rate is."
- Break down by channel: "Break down Paying Users and Revenue over the last 7 days by Source Channel, and list the average payment per paying user for each channel."
- Break down by new and returning payers: "Split the payments over the last 7 days by 'is first payment', and show how many users and how much revenue come from first purchases and repeat purchases."
- Segment by amount: "Segment the paying users over the last 7 days by Cum. Revenue (0–30, 30–98, 98–328, 328–648, and above 648), show the share of users in each tier, and then list the bundles with the highest Revenue."
When the analysis is done, have the AI write it up as a report that separates facts, judgments, and recommended actions:
Turn the analysis we just did into a report with this fixed structure:
summary of conclusions, data definitions, key facts, cause analysis, items to verify, recommended actions.
Keep facts and judgments separate, and mark anything speculative as to be verified instead of presenting it as a conclusion.
Audit and govern data assets
The semantic quality of your data assets sets the ceiling on how well AI can retrieve data: when event names are messy, properties have no comments, and definitions are inconsistent, AI can only guess. Audit first, then analyze.
| Scenario | Prompt to copy | Read/write |
|---|---|---|
| Asset audit | Audit the tracking assets in my current project: count the total number of events and properties; find events and properties that are missing display names or comments; find events with non-standard names; and find events with no data reported in the last 90 days. First output the scope of the check, the rules used, and a categorized list. Don't modify any assets. | Read-only |
| Semantic completion | Based on the audit results, generate suggestions for events and properties that are missing display names or comments. Output the original field name, suggested display name, suggested comment, and reason for the change. Give me only the suggestion table; I'll review it before anything is changed. | Run after confirmation |
| Data quality self-check | Check data quality over the last 7 days: whether the reporting volume of core events suddenly dropped to zero or spiked; the null rate and abnormal enum values of key properties; and assets that are disconnected or have had no data for a long time. Output the symptoms, possible causes, and evidence that needs manual confirmation. Don't modify any assets. | Read-only |
"No data" doesn't mean "useless": it's normal for events from periodic campaigns not to be reported most of the time. Check with the business team before you clean anything up.
Design tracking plans and generate tracking code
AI can give you a plan that works in practice only if you explain the business flow clearly. Instead of just saying "Design tracking for me", give it the complete user path and the metrics you care about most:
Generate a tracking plan for the quest module.
Business goal: understand how players complete quests and where they drop off, find the quests where players get stuck, and see how rewards affect retention.
Player behavior path: open the quest list → accept a quest → do the quest → complete it → claim the reward → leave.
Definition: completed = the quest goal is achieved, which is not the same as claiming the reward.
Dimensions needed: quest type, time to complete, reward type, next action after completion; player level, account type.
The AI outputs a first draft of the plan for review, including event names, display names, trigger timing, properties, property types, sample values, and validation methods, and reuses existing super properties in the project where possible. After the plan passes review, you can go on to generate code:
Generate (Android / iOS / Web / server-side) tracking code for me based on the tracking plan.
For the first generation, we recommend outputting code snippet files and merging them after a manual review. For specific API parameters, the SDK documentation for the corresponding platform prevails.
From analysis to engagement
Requires the Engage module. Push channels must first be configured and enabled in Agentic Engine, and the events and properties referenced in audience conditions must already exist.
| Step | Prompt to copy | Read/write |
|---|---|---|
| Engagement suggestions | Based on the analysis conclusions we just reached, generate engagement suggestions in the format "target audience, trigger conditions, recommended actions, expected metrics to observe, risks and exclusion conditions". Give me the plan first; don't create any audiences or outreach tasks. | Read-only |
| Journey | Turn the care outreach for (target audience) into a journey. First list a draft: audience definition, trigger conditions, wait conditions, outreach channels, frequency control rules, and exit conditions. Create it only after I confirm. | Run after confirmation |
| Performance analysis | Show me how (journey name) performed over the last 7 days: entered users, reached users, converted users, and exit reasons at each node, with the definition of each metric. | Read-only |
| Performance dashboard | Build a dashboard of this journey's performance, including goal metrics, process metrics, segmentation dimensions, and a time filter. Give me a configuration draft first, and create it only after I confirm. | Run after confirmation |
Cross-system workflows and scheduled tasks
For cross-system workflows, first install the CLI or MCP for the corresponding external tool in your AI agent (for example, lark-cli for Feishu). Otherwise, the prompts below will fail. For external actions such as sending messages or creating documents, always review a draft and confirm first.
| Scenario | Prompt to copy |
|---|---|
| Multi-source data integration | Combine the payment data in Agentic Engine with the campaign data in (Feishu sheet) into one report aligned by day. First list the data granularity, date fields, metric definitions, and missing-value rules on both sides. Merge them only after I confirm, and don't modify the external file. |
| Daily report to a work group | Check today's active user data, turn it into a daily report, and send it to our work group. Include core metrics, period-over-period changes, anomalies, and links to the original analysis. Show me a draft first, and send it only after I confirm. |
| Weekly report as an online doc | Turn this week's data into a weekly report as a Feishu doc, structured as: metrics overview, daily trends, interpretation of changes, review of engagement actions, and to-dos for next week. Generate a draft first, and create the doc only after I confirm. |
| Scheduled monitoring | Create an automation for me: after a version release, query the core metrics (metric 1, metric 2) of (project) every 30 minutes, turn the results into a monitoring card, and send it to (Feishu group). If any metric drops more than 10% below its average over the previous 7 days, highlight it in red in the message. First list the execution plan, query definitions, and message format, and turn it on only after I confirm. |
Run a scheduled task manually once first, and turn it on only after you confirm that the format and definitions are correct. For monitoring, start at an interval of 30 minutes; for daily reports, once a day is enough. To set up recurring tasks in Agentic Engine, see Automations.
Create and reuse analysis assets (run after confirmation)
| Asset | Applicable questions | Confirm before creating |
|---|---|---|
| Custom property | Combine multiple original fields into an analysis dimension | Formula, null handling, scope of impact |
| User tags | Lock in stable user classification rules | Calculation period, data source, update frequency |
| Cohorts | Select audiences to analyze or engage | Entry conditions, exclusion conditions, validity period |
| Reports and dashboards | Standardize how high-frequency metrics are viewed | Metric definitions, filters, access permissions |
| Cross-project reuse | Move common analysis structures to other projects | Event mapping, property mapping, definition differences |
Design a draft (custom property / tag / cohort / dashboard) for (goal).
First list the events and properties it depends on, the calculation or filter logic, the update method, permissions, and migration risks.
Don't create it yet; wait for my confirmation.
When you have many projects, batch operations save the most time. For example: "Using the structure of the version monitoring dashboard, create one for each of projects A, B, and C, and list the differences when you're done."
DataOps Platform
Requires the DataOps Platform.
| Scenario | Prompt to copy |
|---|---|
| Database, table, and Flow queries | List the databases, tables, and Flows accessible in the current environment, summarized by last update time and status. |
| Data retrieval and debugging | Based on (business question), generate a query approach and a draft SQL statement. First explain the tables, join conditions, time range, and validation method. Don't perform any write operations. |
| Flow building | Design a Flow for (business domain): list the node orchestration, schedule, and release plan. Don't create it yet. |
| Wide table processing | Process (event table) into (wide table). First give me the field list, aggregation granularity, partitioning strategy, and Incremental Update logic, and create the table and Flow only after I confirm. |
| Run troubleshooting | Summarize the failed instances over the last (N) days, categorize them by Flow and failure reason, and suggest fixes. |
More scenarios
- Local data integration: "Import the data in (local file path) into Agentic Engine. First identify the file structure and list the field mappings and types. Run the import only after I confirm."
- Community insights (requires Omni Insights): "Summarize the community discussions about (new version) over the past week, including trending topics, positive and negative feedback, and risks that need priority attention."
- Knowledge base: "Find pages about (topic) in (knowledge base name), read the original text, then answer (question) and cite the source pages."
- Platform management (requires admin permissions): "List the channels configured in the system and the usage summary for the last 30 days. Read-only; don't modify anything."
The CLI can do more than can be listed here. Just tell the AI what you need, and it determines whether it can do it and what configuration is still missing.
Verify results
Whenever you get a number, ask four questions first: Which event was used? Which metric definition? What time range? What filters? If a definition is wrong, correct it on the spot and have the AI rerun the query. If the retrieved data doesn't match a dashboard, have the AI list its query conditions one by one and compare them with the configuration of the report in the dashboard.
| Level | Description | Example |
|---|---|---|
| Fact | Directly reproducible from data | "The payment conversion rate over the last 7 days was 30.46%." |
| Judgment | An interpretation of facts | "Drop-off is concentrated between the store and starting a top-up, possibly related to how prices are shown." |
| To be verified | Current data isn't enough to confirm it | "Needs to be verified with store impression tracking." |
When the AI stops to ask you "Which one does this term mean?", it's not an error: when a term matches multiple metrics or events, the AI leaves the choice of definition to you. If the same ambiguity keeps coming up, capture the default definition in a Skill or Knowledge base.
Command reference
For daily use, you don't need to memorize commands; the AI agent finds the right command through Skills. When you troubleshoot or write scripts, view the help like this. You can keep appending --help to subcommands at each level:
ae-cli --help
ae-cli analysis --help
ae-cli project member --help
| Category | Root commands | Purpose |
|---|---|---|
| Analytics and projects | analysis、analysis-meta、analysis-governance、project、metadata、personal-semantic-preference、project-semantic | Reports, dashboards, ad hoc analysis, alerts, tags, and cohorts; event and property catalogs, metrics, and tracking governance; data asset search and lineage; projects, members, roles, and permissions; data table and dimension table binding; personal semantic preferences; project asset package export |
| Data and tracking | tracking、data-integration | Tracking plans, SDK samples, collection diagnostics, and code generation; checking, transforming, and uploading local CSV, JSON, and Excel data |
| Community insights | community | Community posts, comments, topics, sentiment, live streams, and reports |
| Engagement | engage-flow、engage-task、engage-setting、engage-scene、engage-activity、engage-workbench、engage-query | Engagement flows, tasks and outreach content, channel and audience settings, scenes and strategies, campaigns and special topics, workbench and to-dos, engagement queries and async exports |
| DataOps Platform | dataops_repo、dataops_datatable、dataops_flow、dataops_ide、dataops_integration、dataops_operations | Data warehouses and data sources, tables and views, development flows and scheduling, IDE queries, data integration, operations and alerts |
| Agent platform | kb、agent、context、memory、team、system | Knowledge bases and Q&A; Agents, automations, models, MCP, Skills, and attachments; current page context; user memory; Agent Team; system administration such as members, sandboxes, usage, quotas, and channels |
| General tools | capability、auth、config、sync、model、update | Capability discovery and generic invocation; login and accounts; environment management; syncing Skills and MCP; switching sandbox models; syncing to the required version |
Capability Gateway
Long-tail capabilities without dedicated commands are discovered and called dynamically through the Capability Gateway:
ae-cli capability list --domain analysis
ae-cli capability search "dashboard list" --domain analysis
ae-cli capability inspect analysis.dashboard.list
ae-cli capability dry-run analysis.dashboard.list --input '{"project_id":1}'
ae-cli capability run analysis.dashboard.list --input '{"project_id":1}'
--input accepts inline JSON, a JSON file path, or a file path prefixed with @, and you can also use - to read from standard input. dry-run already includes parameter validation and shows the risk level. Use run only after you confirm everything is correct.
Output format
By default, commands output a unified JSON structure (ok, data, _notice) that's easy for AI agents to read:
--format table: Supported list commands display results as a table for easier manual review.--jq <expression>: Filters the business result before output.--dry-run: Previews only, without running.--yes: Skips the interactive confirmation for high-risk write operations. Use it only after you've confirmed the scope of impact.
Multiple environments and accounts
Credentials are stored separately for each Agentic Engine address. When you use both test and production environments, manage them with config:
ae-cli config list
ae-cli config add https://host-b.example.com --label staging --use
ae-cli config use staging
ae-cli config current
When you need multiple accounts in the same environment, add --add to the login command, then use ae-cli auth list to view them and ae-cli auth use --account <account> to switch between them. ae-cli auth logout logs out of the current account. Running ae-cli config or ae-cli auth directly in a terminal opens an interactive selector.
Security and permissions
- The CLI never gets permissions beyond your account's scope. Company isolation, resource ownership, and final permissions are all verified by the server.
- For write operations, do a dry-run first, or have the AI propose the plan, scope of impact, and rollback method first, and run it only after you confirm. High-risk operations such as deletion also ask for a second confirmation.
- Don't paste passwords, tokens, or other credentials into the conversation. The CLI output never includes tokens either.
- Admin commands under
systemrequire the account to have the root or agent_admin role. If you get a permission error, don't retry or work around it; contact your admin to confirm. - Install only Node.js,
@thinkingai/ae-cli, and the official Skills. Don't disable TLS verification, and don't use untrusted mirror sources.
FAQ
Troubleshoot installation and authorization issues
| Symptom | Common causes | Solution |
|---|---|---|
| Installation fails or downloads time out | Network, npm registry, or proxy restrictions | Check your network and proxy, use a dependency source approved by your team, and keep the full error message |
| Still not logged in after authorization | Browser authorization wasn't completed, or the device code expired | Run the login command again to complete authorization, then check the login status |
| Target project not found | The account has no permission, or you're connected to the wrong environment | Check the Agentic Engine address, account, and project ID |
| The AI doesn't recognize Agentic Engine capabilities | Skills aren't installed, or the current AI agent hasn't reloaded them | Reinstall the Skills, then restart the AI agent |
| "Command not found" or version mismatch | The CLI or Skills version differs from the version the environment requires | Run ae-cli update --host <address>, then restart the AI agent |
| Can't connect to a private deployment | Mismatched address, port, certificate, or intranet configuration | Verify the connection parameters with your deployment team, then check the proxy and certificates |
Can I treat the AI's conclusions as facts?
No. First look at the metric definitions, time range, and filters it used. Data results are facts; explanations of causes are judgments that need further verification. Important business decisions should still be reviewed by the person responsible.
Why do I sometimes get different answers to the same question?
The question may be missing a time range, definition, or dimension, or the semantic information in the project may be incomplete. Turn high-frequency tasks with fixed definitions into Skills, and for exploratory questions, let the AI ask more follow-up questions.
Why can't I find a capability that others can use?
Check the following in order: the CLI version, the version of the Skills the AI has loaded, whether the capability is deployed in the current environment, and whether your account has permission. You can start by running ae-cli capability list to see which capabilities are available in the current environment.
What should I provide when I run into a problem?
Give your customer success manager the following: the Agentic Engine address, the output of ae-cli --version, the target project, the steps to reproduce, and the full error message. Don't send passwords, tokens, or other credentials.
Related links
- ae-cli source code and Skills: github.com/ThinkingAIAgenticEngine/ae-cli
- Installation and upgrade guide (for AI agents to read): cli-installation-guide.md
- Curated scenario Skills: github.com/ThinkingAIAgenticEngine/scenario-skills