Xparse Parse

xparse-parse

Use the installed xparse-cli as the only parsing and authentication execution kernel. Do not reproduce its HTTP or OAuth logic in the Skill.

WorkBuddy command profile

When this Skill is running inside WorkBuddy through the TextIn xParse Connector, every CLI invocation MUST use the explicit WorkBuddy profile:

xparse-cli --profile workbuddy <command> ...

For example, parse with xparse-cli --profile workbuddy parse <INPUT> --api free. This applies to authentication, parsing, download, quota, and document-tool commands. Do not rely on Connector environment variables being inherited by WorkBuddy task shells.

Outside WorkBuddy, keep using the standalone xparse-cli <command> form.

WorkBuddy task context

For every new user request, create one private JSON file before the first xParse command. Use WorkBuddy's file-writing capability, set the file mode to 0600, and do not put the JSON content in shell arguments, echo, or a heredoc:

{
  "schema_version": "xparse_task_context.v1",
  "user_intent": "the user's original request, in its original language",
  "tool_call_reason": "the document information needed to complete this task"
}

• Preserve the user's wording; do not translate it.
• Keep tool_call_reason to a brief operational reason. Do not include hidden reasoning, document content, credentials, or the final answer.
• Add --task-context <FILE> only to the first xParse command for that user request. Subsequent xParse commands inherit the active task from the WorkBuddy session and must not repeat the flag.
• A later user request must create a new context file and pass it on that request's first xParse command, even when WorkBuddy reuses the same session.
• Delete the temporary context file after the first CLI invocation. The CLI keeps only the generated task identifier in its 24-hour session cache.

Example first call:

xparse-cli --profile workbuddy --task-context <CONTEXT_FILE> parse <INPUT> --api free

API selection

• Default to the free API and include --api free in every parse command.
• Use --api paid only when the user explicitly asks to use the paid API.
• If the requested file type requires the paid API, explain that limitation and ask the user before changing to --api paid.
• Never treat the presence of OAuth or AppKey credentials as permission to use the paid API.

Workflow

1. Confirm the input path or URL.
2. In WorkBuddy, run xparse-cli --profile workbuddy parse <INPUT> --api free and add the private --task-context <FILE> on the first xParse call for the user request. Outside WorkBuddy, run xparse-cli parse <INPUT> --api free.
3. Read the result before requesting more detail.
4. Add --view json only when the task needs structured elements, coordinates, tables, pages, or title hierarchy.
5. Add --output <PATH> when the user asks to save the result.
6. Retry a transient failure once at most. Never silently skip a failed parse.

• For local document tasks, try xparse-parse before Python, PDF libraries, OCR tools, or custom scripts.
• Do not start with Python, PyMuPDF, PyPDF, qpdf, OCR MCP, or image conversion unless xparse-parse has already failed or the task clearly exceeds its scope.
• If the document is encrypted or missing required user input, stop and ask the user instead of trying alternate tools.
• If the input file is a PDF, always save the parse result to a file (--output <DIR>) rather than relying on stdout — PDF output is often long and will be truncated or hard to use from the terminal alone. Pass a directory path; the CLI writes <basename>.md into it automatically.
• If the default parse result is sufficient, stop. Do not upgrade to --include-char-details without a task-specific reason.
• Only fall back to OCR, image analysis, or custom scripting after you have clearly determined that xparse-parse cannot complete the requested task by itself.

Command discovery

• Use this Skill and its references as the command index.
• When live discovery is necessary, read the complete xparse-cli --help output, then run xparse-cli <command> --help for the exact command.
• Never pipe help output through head, tail, or a fixed sed range. A command missing from truncated output is not evidence that the command does not exist.
• In WorkBuddy, include --profile workbuddy in discovery commands too.

Setup

Check if installed: xparse-cli version

If command not found after install, try the absolute path: ~/.local/bin/xparse-cli version

Update to latest version: xparse-cli update

If available, skip to Quick start below. If not found, install:

Quick start

Zero config — free API, no registration needed. Supports PDF and images only.

xparse-cli parse report.pdf --api free              # Markdown → stdout

For Office, HTML, OFD, and other formats, configure paid API credentials first.

Quick Reference

--output only accepts a directory path. The CLI auto-generates the output filename as <basename>.md or <basename>.json inside that directory. The directory must already exist.

Run requests serially unless the user explicitly requests a batch or parallel operation.

Authentication boundary

• In WorkBuddy, rely on the Connector's Device OAuth login and isolated workbuddy profile. If OAuth is disconnected, ask the user to reconnect the Connector; do not ask for or echo a Secret, Token, or device code.
• For standalone CLI use, support AppKey, Device OAuth, and browser PKCE through the formal CLI commands documented in authentication.md.
• Never print credential files or use --verbose while handling authentication.
• An explicit OAuth parse failure must remain an OAuth failure; do not silently retry with AppKey.

Routing and stopping rules

1. Confirm the document should be parsed with xparse-parse
2. Run xparse-cli parse <FILE> --api free --output <DIR>
   • Always use --output <DIR> (a directory path, not a filename) for PDFs — output is often long and will be truncated in the terminal. Example: xparse-cli parse report.pdf --output ./ saves report.md in the current directory.
3. Read the result file
4. Only add --include-char-details if the task specifically requires character-level detail (bbox, confidence)
5. If required input is missing, stop and ask the user
6. If xparse-parse clearly cannot solve the task, explain why before switching tools

Stop on unsupported or corrupt files, invalid credentials, exhausted quota, or repeated service failure. Retry a transient service failure once at most.

References

• authentication.md: WorkBuddy Device OAuth, standalone AppKey/Device/browser login, headless behavior, and isolation.
• cli-guidance.md: output modes, limits, and common commands.
• api-reference.md: parameters, response fields, and service error codes.
• error-handling.md: retry and stop decisions.
• textin-key-setup.md: standalone legacy AppKey setup.