Run long research in the cloud
Send a research question to CCNeed and keep working with the Agent you already use.
CCNEED CLI
Use the CCNeed CLI and native Agent plugin to collect and export data for your own AI assistant, or send knowledge bases and files to CCNeed for cloud research and reports.
Before you begin
ccneed auth status --verify✓ Signed in to ccneed.ai
✓ CCNeed plugin loaded in Codex
ccneed run "Research customer needs" --kb-id KB_IDResearch submitted
The task is running in your CCNeed workspace.
✓ Once the task completes, review the findings.
One CLI, two ways to work
The CLI connects your AI assistant to CCNeed. Its matching native plugin bundles the Skill and collection hooks to help your Agent prepare plans, wait for your confirmation, and deliver results.
Send a research question to CCNeed and keep working with the Agent you already use.
Collect into a knowledge base with an approved plan, then export CSV or JSON for your own Agent. Existing data can be exported directly.
Review keywords, collection targets, and credits before approving execution in your Agent’s native permission UI. Website access and choices that need your input remain yours.
Quick start
Choose your Agent and install the global ccneed command and matching plugin. Check the host result, complete pending steps, then restart your Agent and trust the plugin hooks.
The CLI returns an authorization link and confirmation code. Open the page, check the code, approve access yourself, then complete sign-in in the terminal.
For new data, let your Agent prepare a collection plan, then confirm it and approve execution. Export an existing knowledge base directly, or use it with uploaded files for cloud research.
After collection and tagging finish, your Agent normally delivers CSV automatically; you can request JSON instead. For cloud research, read or export the report after the task completes.
npx @validflow/ccneed-cli@latest install --agent codexnpx @validflow/ccneed-cli@latest install --agent claudenpx @validflow/ccneed-cli@latest install --agent workbuddyccneed version --no-update-checkChoose your host, or use comma-separated names for several. Check each host’s installed / action_required / failed result. WorkBuddy desktop needs the native plugin installation step shown in the result. Restart your host, trust the hooks, and keep manual execution approval enabled.
ccneed auth loginccneed auth login --complete --timeout 60sccneed auth status --verifyApprove access yourself in the browser before running --complete. The CLI does not read website cookies or ask for your password.
ccneed kb listccneed files upload ./research-brief.pdfccneed run "Research customer needs" --kb-id KB_ID --file-id FILE_IDUse the returned numeric KB_ID, the uploaded file’s UUID for FILE_ID, and the research task’s UUIDs for THREAD_UUID and TURN_UUID. Bind a knowledge base, a file, or both; bindings cannot be removed after submission.
ccneed tasks get --thread-id THREAD_UUID --turn-id TURN_UUIDccneed tasks watch --thread-id THREAD_UUID --turn-id TURN_UUID --timeout 60sWhen checking progress, distinguish queued, running, waiting for your input, and completed states.
DATA COLLECTION & EXPORT
Describe your research to your Agent and let it create plan.json using the plan schema. Review the plan, then separately approve execution. For an existing knowledge base, go straight to export without creating a cloud research conversation.
Read the plan schema and collection guidekb plan validates and quotes only; it does not create a knowledge base, charge credits, or collect data. Your Agent presents the requirement, each platform’s entity and other keywords, targets, total count, estimated credits, balance, and adjustments. Edit either keyword group or the quotas, keeping at least one entity per platform; changes require validation and confirmation again.
ccneed kb plan --plan-file /ABSOLUTE/PATH/plan.json --output /ABSOLUTE/PATH/prepared.jsonAfter confirming the plan, approve this kb start execution in your host’s native permission UI. Use the complete, unmodified prepared.json; prepare again if the plan expires or credits are insufficient. REQUEST_UUID identifies this execution. If its result is unknown, check status first and keep the same UUID when retrying.
ccneed kb start --plan-file /ABSOLUTE/PATH/prepared.json --request-id REQUEST_UUIDUse the actual numeric KB_ID from the start response to check status; stats shows counts and distributions. Keep waiting while collection or tagging is in progress. Acceptance or partial data does not mean completion. Complete result pages can take the actual count above the collection target.
ccneed kb get --kb-id KB_IDccneed kb stats --kb-id KB_IDAfter new collection finishes, your Agent normally exports and delivers CSV automatically; request JSON or a destination if you prefer. --output is optional: the server supplies the default filename, and existing files are never overwritten. Data export is separate from PDF/Markdown research report export.
ccneed kb export --kb-id KB_ID --format csvccneed kb export --kb-id KB_ID --format json --output /ABSOLUTE/PATH/data.jsonReplace /ABSOLUTE/PATH with an actual absolute path on your computer and KB_ID with the returned numeric ID. Use absolute plan paths in Codex and start with the complete prepared.json you just reviewed.
CODEX WALKTHROUGH
The installer installs the CLI and registers its matching native plugin. This example runs cloud research with an existing knowledge base and file. For new data, first prepare and approve a plan using the collection workflow above.
01 · Install for Codex
Run the official install command in your terminal. Check that the Codex plugin result is installed; complete any pending steps shown in the result.
Restart Codex and confirm the plugin Skill and hooks are loaded and trusted. Keep native manual approval enabled for collection.
Codex · CCNeed Skill
Codex runs the CLI
You ask Codex
Use the Product Feedback knowledge base and ./customer-feedback.csv to research the main obstacles new users face when getting started. Keep the source references.
I’ll verify sign-in and find the available knowledge base first. If access is needed, I’ll show you the link and confirmation code so you can approve it in your browser.
Codex runs the CLI
ccneed auth status --verifyccneed kb listccneed files upload ./customer-feedback.csvccneed run "Research new-user onboarding friction" --kb-id KB_ID --file-id FILE_IDccneed tasks watch --thread-id THREAD_UUID --turn-id TURN_UUID --timeout 60sOn first sign-in, Codex starts ccneed auth login. You approve access in the browser before Codex completes sign-in.
When the research is complete
Codex reads the report and organizes key findings, source evidence, and questions that still need review.
Command reference
Run commands in your terminal or describe the task to an Agent with the CCNeed plugin enabled. Replace example IDs and paths with your actual values.
Read the full READMEccneed auth status --verifyccneed account overviewccneed kb listccneed kb stats --kb-id KB_IDccneed kb export --kb-id KB_ID --format csvccneed kb createccneed threads listccneed files upload ./research-brief.pdfccneed <command> --helpService availability: These commands were checked against CLI 0.1.11. Collection, tagging, and export also depend on the matching CCNeed service APIs being deployed; check command help and service responses. Regular users connect to https://ccneed.ai by default and do not need --api-url.
The official installer installs ccneed globally, registers native plugins for your selected Agents, and configures collection execution approval rules. It does not modify your current project. The plugin bundles the shared Skill and collection hooks.
Run npx @validflow/ccneed-cli@latest install --agent ... again, naming every host you want to update. Check each host’s result, finish pending plugin installation or trust steps, and reload your Agent.
No. Your Agent can prepare a plan with kb plan and submit collection with kb start after you confirm the plan and approve execution. kb create still returns the website creation entry.
No. Use kb export to export an existing knowledge base as CSV or JSON. For new collection, your Agent normally exports CSV after collection and tagging finish. Cloud research and reports are a separate, optional workflow.
No. The CLI provides a website authorization link and confirmation code. You approve it on the page; credentials are stored through the system credential store.
Yes. The companion Skill can read reports on request. Use PDF export to read the full report or download the original Markdown when you need the source file.
InsightFlow
Use InsightFlow to find what customers are discussing, then bring the research into your Agent with the CLI.