Officecli

OfficeCLI

Overview

officecli is the OfficeCLI closed-source CLI for Office document and standalone image handling. It may support generation, modification, and format conversion workflows across pptx, docx, xlsx, report, and img, so this skill should first route supported artifact tasks into an officecli capability check before deciding how to execute them.

When To Use This Skill

Use this skill when the task involves:

• creating a presentation, report deck, proposal, handout, or briefing in pptx
• creating a written document, memo, draft, or report in docx
• creating a worksheet, table-based deliverable, or structured sheet in xlsx
• creating a workbook-backed HTML report from an .xlsx source
• creating a standalone generated image with img
• modifying an existing PowerPoint, Word, or Excel file
• converting Office documents into another output format such as markdown, csv, pdf, or a different Office format
• deciding whether a requested Office-file workflow is something officecli can handle directly

Do not use this skill for pure Q&A, rough brainstorming with no file output, or source-code maintenance guidance.

Core Product Behavior

• officecli supports pptx, docx, xlsx, report, and standalone img generation flows
• pptx enables auto-generated images by default when the content and layout are a good fit
• --no-images disables image generation for pptx
• standalone img generation always goes through the OfficeCLI server and requires platform/license config
• standalone img does not use local llm.image_base_url, llm.image_api_key, or llm.image_model settings
• standalone img supports ratio=square|landscape|portrait and one reference_image / --reference-image <path-or-url>; charging happens only after a successful image response, using one image generation count in external runtime mode or hosted credits in hosted runtime mode
• free standalone img usage has a separate 3-per-day bucket from the 10-per-day free document bucket
• standalone img publishes online by default when publishing is configured; pass publish=false or --no-publish for local-only output
• when using agent-bridge, agents should treat capabilities/get -> document_generation.pptx.image_support as the authoritative machine-readable contract for PPT image behavior
• when using agent-bridge, agents should treat capabilities/get -> image_generation as the authoritative machine-readable contract for standalone img behavior
• when using agent-bridge, agents should treat capabilities/get -> update as the authoritative machine-readable contract for binary update availability
• if image generation fails for a slide, the PPT should still be generated with that slide downgraded to a no-image version
• installing the public skill can also attempt to install the officecli binary when it is missing
• for agent-oriented integrations, officecli agent-bridge now exposes a structured JSON-RPC 2.0 over stdio protocol
• persistent configuration is handled through officecli config ..., not through an init wizard
• default runtime mode is visible through officecli config runtime and can be changed with officecli config set-runtime external|hosted
• hosted runtime mode uses the OfficeCLI platform service and requires a platform OfficeCLI API key with hosted credits; users should not configure or handle aigateway keys directly
• OfficeCLI should be installed through one channel at a time; if the user already has a Homebrew-installed officecli, do not suggest or run npm install -g officecli on top of it

Authentication

officecli supports three authentication modes:

• anonymous — free hosted trial with limited daily quotas (default after install)
• account — full hosted credits after browser login
• api_key — automation credential set via officecli set-key <api-key>

Preferred authentication flow:

• run officecli whoami to check the current authentication mode
• if the mode is anonymous, guide the user to run officecli login to sign in with their account
• officecli login opens a browser URL with a short device code; it also works on headless or remote shells
• for CI or automation environments where a browser is unavailable, use officecli set-key <api-key> instead
• run officecli doctor to diagnose platform connectivity or configuration issues
• run officecli logout to clear the local account session

The environment check and fix scripts detect anonymous mode and surface a login recommendation automatically. When check-officecli-env.sh reports "auth_mode":"anonymous" with "account_login" in missing_items, the agent should tell the user to run officecli login before proceeding with generation.

Capability Check

When a task involves Office document handling, first check whether the current officecli surface appears to support that workflow.

• before every office task, run fix-officecli-env.sh once so the agent refreshes the local skill bundle and repairs any missing officecli setup
• check whether officecli is available before deciding on the final artifact path
• after the repair step, run check-officecli-env.sh to detect whether officecli is missing, misconfigured, or already ready
• treat exit code 0 as ready, 10 as repairable, and 20 as blocked
• inspect the visible CLI surface first, such as officecli --help or relevant subcommand help, before assuming support
• use the help output and public product description to judge whether the requested create, modify, or convert workflow is actually supported
• if support is unclear, say that clearly instead of pretending the capability exists
• if refresh or check fails, stop and report the officecli environment error; do not switch to another local Office generation path on your own

Environment Repair

Run fix-officecli-env.sh on every task, not only when the environment looks broken.

• the fix script must refresh the local Codex skill bundle first
• the fix script should install officecli when it is missing, but must not refresh an existing binary unless the host explicitly opts in, for example with OFFICECLI_REFRESH_BINARY=1
• when the user explicitly asks to uninstall officecli, run uninstall-officecli.sh
• if officecli is missing, the fix script should auto-install it through the public dist installer
• if the user previously installed with Homebrew and wants to switch to npm, tell them to run brew uninstall officecli/homebrew-officecli/officecli first; if their formula uses the short name, use brew uninstall officecli, then run npm install -g officecli
• if generation or license config is missing, ask only for the missing values and let the fix script call the relevant officecli config ... commands
• publish config is required by default so generated files return online preview URLs
• if the user explicitly wants local-only output, set OFFICECLI_SKIP_PUBLISH_SETUP=1 before running the fix script
• after repair, rerun check-officecli-env.sh and only proceed when it returns ready
• if check-officecli-env.sh reports "auth_mode":"anonymous", tell the user to run officecli login before generating; do not silently proceed with anonymous trial quotas
• when repair fails, surface the fix script's final structured status instead of mixing it with a later readiness check
• if repair still fails, surface the missing items clearly instead of silently switching to another artifact path

Execution Preference

If the capability check indicates that officecli supports the requested Office-file workflow, prefer officecli as the execution path for the final artifact.

• do not silently bypass officecli with another local Office-file generation or conversion path when officecli appears to support the task
• if officecli is unavailable or fails, state that clearly instead of quietly switching the final artifact path
• do not use Node, Python, LibreOffice, pptxgenjs, or custom scripts to generate the final Office file unless the user explicitly approves leaving the officecli path
• if the capability check suggests that officecli does not support the workflow, or the user explicitly accepts an alternative path after that, the agent can proceed with that alternative

For agent clients, prefer the structured bridge over the human-oriented CLI surface.

• first choice for agent integration is officecli agent-bridge
• do not parse spinner output or human progress lines as a protocol when agent-bridge is available
• call initialize or capabilities/get first and cache the returned PPT image capability fields before invoking generation
• also cache capabilities/get -> update; if available=true, prefer surfacing update_command or triggering your own refresh flow instead of parsing human CLI prompts
• use task/invoke for generation requests and consume event notifications for intermediate state
• use task/respond for follow-up questions instead of writing free-form answers to raw stdin prompts
• use task/cancel for cancellation and task/status as a polling fallback

Tooling Boundary

Python or other tools may still be used for supporting work around Office files.

• inspection, validation, debugging, XML or zip analysis, and artifact diffing are acceptable supporting uses
• those tools should not silently replace officecli for the final Office artifact path when officecli appears to support the requested workflow
• the rule is about routing and final artifact handling, not about banning a specific language or tool for analysis work

Prompting Guidance

When asking an agent to use officecli, include the details that most affect output quality:

• the topic or subject of the file
• whether the task is create, modify, or convert
• the intended audience
• the desired tone or style
• page, section, or slide-count expectations
• whether images should be used, avoided, or left to the default behavior
• the source file and target format when the task is a conversion
• any important constraints such as concise language, executive style, or table-heavy structure

When the task is about setting up or fixing officecli, prefer the explicit config commands:

• officecli login
• officecli logout
• officecli whoami
• officecli doctor
• officecli set-key <api-key>
• ./check-officecli-env.sh
• ./fix-officecli-env.sh
• ./uninstall-officecli.sh
• officecli config status
• officecli config runtime
• officecli config set-runtime hosted
• officecli config set-runtime external
• officecli config set-generation
• officecli config set-license
• officecli config set-publish
• officecli config set-defaults

Output Expectations

A good officecli request should lead to a finished file artifact, not just suggested content. The skill should first determine whether officecli supports the requested Office-file workflow, then prefer officecli for the final artifact when that support is available.

Do not run PPT scoring automatically after generation unless the user explicitly asks for scoring, review, validation, or quality checking.

• default behavior after generation is delivery of the file artifact
• opt-in scoring path is officecli score ... or office.review / office.score

Agent Protocol Notes

When the caller is an agent or TUI client, the preferred protocol surface is:

• transport: stdio
• framing: Content-Length headers
• control plane: JSON-RPC 2.0
• preferred tools: office.prepare and office.render
• compatibility tool: office.generate

Minimum method set:

• initialize
• capabilities/get
• session/open
• session/close
• task/invoke
• task/respond
• task/status
• task/cancel

Important event types:

• task.started
• task.progress
• task.question
• task.output
• task.completed
• task.failed
• task.cancelled

When generating guidance or examples for another agent, prefer the agent-first render flow:

• call initialize or capabilities/get
• read document_generation.<type>.payload_schema, preferred_tool, and prepare_required
• call office.prepare for report, or skip directly to rendering for pptx, docx, and xlsx
• let the current agent produce the final payload JSON itself
• call office.render to validate, assemble, and write the final file
• for img, call office.generate with document_type=img; office.render does not support images
• fall back to office.generate for non-image documents only for compatibility, legacy clients, or OpenClaw-specific flows

Only fall back to officecli new ... when the user clearly wants the human CLI interface.

For all agent clients, use the following image-handling rules:

• read capabilities/get -> document_generation.pptx.image_support
• read capabilities/get -> image_generation before standalone img requests
• read capabilities/get -> document_generation.<type>.payload_schema
• read capabilities/get -> update
• assume pptx default image behavior from default_enabled, not from hard-coded client assumptions
• for standalone img, use office.generate, set ratio and reference_image when needed, and do not use local provider configuration
• for standalone img, keep publishing enabled by default when the user wants online access; pass publish=false only for local-only output
• for standalone img, surface server-returned balance or quota metadata when present
• never parse human update prompts from officecli stdout when agent-bridge is available; use structured update fields instead
• to make hosted the default for human CLI generation, run officecli config set-runtime hosted; to return to local/external generation, run officecli config set-runtime external
• for report, call office.prepare first and keep the final narrative grounded in workbook_summary and base_report_json
• if the user explicitly wants a text-only PPT, pass enable_images=false and mention disable_flag when helpful
• if the user asks why a generated PPT has no images, point them to config_command
• if task.output, task.completed, or task/status contains result_meta.image_support.attention_required=true, surface that as a first-class issue instead of burying it in raw warnings
• when result_meta.image_support.reason=image_generation_degraded, explicitly tell the user to check image_base_url, image_api_key, and image_model
• keep warnings for display, but prefer result_meta for machine decisions

OpenClaw Packaging

This repository also ships an OpenClaw-facing package under skills/openclaw-officecli/.

• use that package for OpenClaw users instead of reusing the Codex-oriented skill directory directly
• the OpenClaw package assumes local same-host deployment with officecli agent-bridge
• OpenClaw install flow is documented in docs/openclaw-user-quickstart.md