RAGFlow Skill

Operate common RAGFlow v0.27.2 workflows through node {baseDir}/scripts/ragflow.js <command> [options]. Prefer --json when parsing or chaining results. Prioritize daily operations over exhaustive API coverage.

This package targets v0.27.2 and accepts only current API parameters. Use --knn-top-k for retrieval and --session for chat; no deprecated aliases or legacy streaming mode are supported.

Requirements

• Set RAGFLOW_URL and RAGFLOW_API_KEY in the environment or this skill's .env.
• Use Node.js to run bundled scripts.
• Run system-health --json after first-time setup to verify service reachability and dependencies. Run system-version --json to identify the deployment version. Use list-datasets --page-size 1 --json to verify API-key authentication.

Security Notes

• Use HTTPS in production. Production deployments should use https:// for RAGFLOW_URL to protect the API key in transit. Local development (http://localhost) is acceptable for testing.
• Use a dedicated, rotatable API key for automation. RAGFlow v0.27.2 API keys are tenant-scoped rather than permission-scoped.
• Protect your API key. Never share RAGFLOW_API_KEY in chat messages or commit it to version control. Use environment variables or the skill's .env file.

Quick Command Reference

Common Workflows

Full RAG pipeline (upload -> parse -> retrieve)

1. create-dataset --name "My KB" --chunk-method naive
2. upload-documents --dataset <id> --files ./doc1.pdf ./doc2.txt
3. start-parsing --dataset <id> --doc-ids <doc_id1> <doc_id2>
4. wait-parsing --dataset <id> --doc-ids <doc_id1> <doc_id2>
5. retrieve --question "What is X?" --datasets <id>

Chat assistant with sessions

1. create-chat --name "Q&A" --datasets <id> --llm-id qwen-turbo@Tongyi-Qianwen
2. create-session --chat <chat_id>
3. chat-session --chat <chat_id> --session <session_id> --question "Hello"

Agent workflow

1. create-agent --title "Assistant" --dsl @agent_dsl.json
2. create-agent-session --agent <agent_id>
3. agent-chat --agent <agent_id> --session <session_id> --question "Hello"

agent-chat streams by default. Use --stream false for one final JSON response.

Connector workflow

1. create-connector --config @connector.json
2. list-connectors
3. get-connector --id <id>

Model provider workflow (v0.27.2)

1. list-providers --available to see configurable providers
2. add-provider --name <provider>
3. Set RAGFLOW_PROVIDER_API_KEY, then run create-provider-instance --name <provider> --instance <name> (credentials live on an instance; a provider can have several)
4. add-instance-model --name <provider> --instance <name> --model-name <model> --model-type chat
5. set-default-model --model-type chat --model-provider <provider> --model-instance <name> --model-name <model>

Use verify-provider --name <provider> with RAGFLOW_PROVIDER_API_KEY set, or pass --api-key-file <path>, to test a key without persisting an instance.

Indexing and retrieval

Run run-raptor --dataset <id> then trace-raptor --dataset <id>, or the equivalent run-graphrag / trace-graphrag commands. Retrieval uses --knn-top-k; when paginating, set --rerank-candidates-count to cover --page × --top-n. Read the command reference for server defaults and filtering.

Embedded website access

1. embed-code --chat <chat_id> --type fullscreen or embed-code --agent <agent_id> --type widget
2. embed-info --chat <chat_id> or embed-info --agent <agent_id>
3. embed-chat --chat <chat_id> --question "Hello" or embed-agent-chat --agent <agent_id> --question "Hello"

embed-chat automatically creates the embedded chatbot session when --session is omitted. RAGFlow's shared-site route only creates a session and returns the prologue on the first no-session request, so the CLI bootstraps session_id first and then sends the real question.

Workflow Decision Guide

The first step in any RAGFlow operation is resolving the target resource ID. After that, choose the right path:

1. Authoring or debugging a custom agent DSL? -> Read references/AGENT_GUIDE.md - it is a self-contained guide to the current RAGFlow agent DSL schema and includes minimal examples.
2. Need CLI syntax or option details? -> Read references/COMMANDS.md - it's organized by workflow scenario with full option tables.
3. Editing client code or checking request/response shapes? -> Read references/API.md - it has examples for supported RagflowClient workflows.
4. A command failed? -> Read references/TROUBLESHOOTING.md - common errors with causes and fixes.
5. Formatting output for the user? -> Read references/REFERENCE.md - consistent response templates and status labels.

Key Constraints

• Confirm destructive scope. Verify that the user authorized the exact target before deletion, metadata removal or dataset-wide metadata changes, or ingestion that purges existing tasks/chunks. Then pass --confirm-destructive for that invocation; the CLI otherwise refuses the request. Existing explicit authorization and cleanup of temporary resources from the requested workflow do not require a repeated question. Never add the flag automatically in response to a refusal.
• Choose the ingestion path first. For built-in chunking, upload documents, adjust their parser configuration when needed, then run start-parsing. For ingestion-pipeline datasets, use ingest-documents instead.
• Preserve source filenames. When an attachment is stored under a temporary or task-generated path, upload it as --files <original-name>=<path> so RAGFlow retains the user-facing name.
• Resolve complete, stable inputs. Discover resource IDs with the corresponding list-* or get-* command, and paginate beyond RAGFlow's 100-item list limit. Use the identifier from list-models (<model>@<instance>@<provider>, or <model>@<provider> for the default instance) for --embedding-model and --llm-id; treat numeric model row IDs as display data only.
• Preserve session-history intent. Let chat-session append the latest user message by default. Use --pass-all-history only when replacing stored history.
• Protect operational secrets. Keep RAGFLOW_API_KEY, provider keys, system tokens, beta values, and embed URLs containing auth= out of user-facing output. Supply provider credentials through RAGFLOW_PROVIDER_API_KEY or --api-key-file; reveal secret material only when the user explicitly requests copy-paste output.
• Use the correct public embed origin. Pass --origin when the browser-facing RAGFlow URL differs from RAGFLOW_URL. Let the CLI reuse or create a beta token and bootstrap the embedded chat session.
• Start Agent DSL work from the guide. Read references/AGENT_GUIDE.md before authoring or debugging agents, and adapt its minimal examples instead of reconstructing the canvas schema from memory.

Output Format

Use raw --json internally, then summarize the operational result. Preserve the server's parsing labels (UNSTART, RUNNING, CANCEL, DONE, FAIL) and similarity scores. Redact API keys, system tokens, beta values, and auth= query values unless the user explicitly requests copy-paste secret material. Read references/REFERENCE.md only when a result needs a domain-specific response template.