RAGFlow Skill

Use this skill to operate RAGFlow through scripts/ragflow.js. The CLI wraps the full v0.25.x REST API - every action goes through node {baseDir}/scripts/ragflow.js <command> [options]. Prefer --json on any command when the output will be parsed or chained into another step.

Requirements

• Set RAGFLOW_URL and RAGFLOW_API_KEY in the environment or this skill's .env.
• Use Node.js to run bundled scripts.
• Set RAGFLOW_WEB_TOKEN only when list-models needs a web-session token for /v1/llm/my_llms.
• Tune chunk deletion retries only when needed with RAGFLOW_DELETE_CHUNK_RETRIES and RAGFLOW_DELETE_CHUNK_RETRY_DELAY_MS.
• Tune the chunk deletion diagnostic script only when needed with RAGFLOW_REPRO_TIMEOUT_MS, RAGFLOW_REPRO_DELETE_RETRIES, RAGFLOW_REPRO_DELETE_RETRY_DELAY_MS, and RAGFLOW_REPRO_EMBEDDING_MODEL.

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"

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. Need CLI syntax or option details? -> Read references/COMMANDS.md - it's organized by workflow scenario with full option tables.
2. Editing client code or checking request/response shapes? -> Read references/API.md - it has code examples for every RagflowClient method.
3. A command failed? -> Read references/TROUBLESHOOTING.md - common errors with causes and fixes.
4. Formatting output for the user? -> Read references/REFERENCE.md - consistent response templates and status labels.

Key Constraints

• Destructive deletes need confirmation. RAGFlow deletes are immediate and irreversible. Confirm before running delete-datasets, delete-documents, delete-chunks, delete-chats, delete-sessions, or delete-agents - unless the resource is a temporary artifact you created in the same workflow and the user asked you to clean up.
• Upload and parsing are separate steps. RAGFlow does not auto-parse on upload because different documents may need different chunk methods. Upload first, adjust config if needed, then start parsing explicitly.
• Preserve user-uploaded filenames. RAGFlow stores the multipart filename as the document name. If a user attachment is materialized as a task ID or temporary path, pass the original filename inline: upload-documents --files <original-name>=<path>.
• Use v0.25.x route shapes from the references. The RAGFlow API has changed between versions. The routes and payloads in the reference docs match v0.25.x - inventing fallback payloads will produce errors on real servers.
• Tenant model identifiers use the model@provider format. When creating datasets with --embedding-model or chat assistants with --llm-id, the server expects the full identifier, for example text-embedding-v4@Tongyi-Qianwen or qwen-turbo@Tongyi-Qianwen, not a numeric model row ID. Use list-models to discover model names and providers.
• Chat sessions use the API-key SDK route. chat-session posts to /api/v1/chats/{chat_id}/completions with session_id in the body. This is the v0.25.x API-key route - the login-session frontend route is intentionally avoided.
• Embedded access uses beta tokens and embedded sessions. embed-code, embed-info, embed-chat, and embed-agent-chat use the shared-site /api/v1/chatbots/* or /api/v1/agentbots/* routes. If --beta is not supplied, the CLI reuses the first /api/v1/system/tokens item with beta or creates one. For chatbot completions, the CLI auto-bootstraps session_id unless --session is supplied.
• Agent DSL requires specific top-level fields. RAGFlow agents need components, history, path, retrieval, globals, and graph in the DSL. Missing fields cause KeyError at creation time.
• Chunk deletion may need retries. The v0.25.0 server can return rm_chunk deleted chunks 0, expect N due to document-store refresh lag even when the chunk exists. The CLI handles this automatically - it retries after confirming the chunk is still visible via exact ID lookup. If retries still fail, run scripts/repro-delete-chunks.js for a clean diagnosis.

Output Format

When presenting results to the user, follow the templates in references/REFERENCE.md. Key conventions:

• 3+ items with attributes -> Table, abbreviating long IDs
• Sequential steps -> Numbered list
• Parsing status -> Use labels: UNSTART, RUNNING, CANCEL, DONE, FAIL
• Search results -> Table with similarity scores, content as quote blocks
• Errors -> Show code and human-readable message