How to Create a New Word Document with OfficeCLI: Command-Line Guide

Use the office-cli word:create command with the --title flag to generate a new .docx file in OneDrive, optionally specifying a --folder path or --template to copy from existing documents.

The OfficeCLI tool from the iOfficeAI/OfficeCLI repository provides command-line access to Microsoft Office operations through the Microsoft Graph API. Understanding how to create new Word documents programmatically requires examining the command implementation in src/commands/word/create.ts and its integration with the authentication and service layers.

Understanding the word:create Command Architecture

The OfficeCLI is built on the oclif framework, which structures each operation as a discrete command class. When you execute a document creation instruction, the CLI parses your input and routes it to the WordCreateCommand class defined in src/commands/word/create.ts.

The architecture follows a clear separation of concerns:

• Command Layer (src/commands/word/create.ts): Defines the word:create command, validates flags, and orchestrates the creation flow
• Authentication Layer (src/lib/auth.ts): Handles Azure AD token acquisition and caching
• Service Layer (src/lib/graphClient.ts): Wraps Microsoft Graph SDK calls that interact with OneDrive and SharePoint
• Utilities (src/lib/utils.ts): Provides path resolution, input validation, and output formatting helpers

Required Parameters and Flags

The word:create command requires specific flags to function correctly. According to the source code in src/commands/word/create.ts, the available options include:

• --title (required): The filename for the new Word document (must include .docx extension)
• --folder (optional): Target folder path in OneDrive (defaults to root if omitted)
• --template (optional): Path to an existing .docx file in OneDrive to use as a template

The command class registers these flags using oclif's flag system:

// src/commands/word/create.ts
static flags = {
  title: Flags.string({ 
    description: 'Name of the new document', 
    required: true 
  }),
  folder: Flags.string({ 
    description: 'Target folder path (default: root)' 
  }),
  template: Flags.string({ 
    description: 'Path to a .docx template to base the new file on' 
  }),
}

How Document Creation Works: Technical Flow

When you run office-cli word:create, the system executes a four-step process defined across multiple source files:

1. Command Parsing: The oclif framework instantiates WordCreateCommand and validates that required flags (--title) are present.

2. Authentication: The command calls getGraphClient() from src/lib/graphClient.ts, which utilizes src/lib/auth.ts to retrieve cached Azure AD tokens or trigger a new authentication flow.

3. Path Resolution: If a --folder flag is provided, src/lib/utils.ts resolves the folder ID through the Microsoft Graph API.

4. Document Creation: The Graph client sends a POST request to Microsoft Graph endpoint /me/drive/items/{folderId}/children to create the blank document or copy from template.

The core implementation logic in src/commands/word/create.ts handles the conditional logic between creating a blank file versus copying from a template:

// src/commands/word/create.ts (execution flow)
async run() {
  const { flags } = await this.parse(WordCreateCommand);
  const client = await getGraphClient();                 
  const folderId = await resolveFolderId(flags.folder); 
  
  const payload = flags.template
    ? await copyTemplate(flags.template, folderId, flags.title)
    : { name: flags.title, file: {} };

  const result = await client
    .api(`/me/drive/items/${folderId}/children`)
    .post(payload);
    
  this.log(`Created: ${result.id} – ${result.webUrl}`);
}

Practical Command Examples

Create a Blank Word Document

Create a simple document in the root of OneDrive:

office-cli word:create --title "Report.docx"

Create in a Specific Folder

Specify a folder path to organize the document:

office-cli word:create \
  --title "QuarterlyPlan.docx" \
  --folder "/Projects/2026"

Create from Template

Use an existing Word template stored in OneDrive to bootstrap the new file:

office-cli word:create \
  --title "Proposal.docx" \
  --template "/Templates/ProposalTemplate.docx"

Expected Output

Upon successful creation, the CLI returns the document ID and sharing URL:

Created: 01Y5ABCDEF1234567890 – https://onedrive.live.com/?cid=...&id=...

Key Implementation Files

Understanding the document creation process requires familiarity with these specific source files in the iOfficeAI/OfficeCLI repository:

• src/commands/word/create.ts: Implements the word:create command and orchestrates the creation workflow
• src/lib/graphClient.ts: Provides the getGraphClient() function and wraps Microsoft Graph SDK interactions
• src/lib/auth.ts: Handles Azure AD token management for authenticated API requests
• src/lib/utils.ts: Contains helper functions for path resolution and input validation
• src/index.ts: The CLI entry point that registers all commands with the oclif framework

Summary

• The word:create command is implemented in src/commands/word/create.ts as a TypeScript class extending oclif's Command base
• Required parameters include --title for the filename, with optional --folder and --template flags for organization and templating
• Authentication occurs through src/lib/auth.ts and the Microsoft Graph API via src/lib/graphClient.ts
• Documents are created via POST requests to Microsoft Graph endpoints, supporting both blank files and template-based copies
• The command outputs the file ID and web URL upon successful creation in OneDrive

Frequently Asked Questions

What authentication does OfficeCLI require to create Word documents?

OfficeCLI requires Azure AD authentication to obtain tokens for Microsoft Graph API access. The src/lib/auth.ts file handles token acquisition and caching, supporting interactive login flows for user accounts. You must authenticate once before running document creation commands, as the CLI stores tokens securely for subsequent operations.

Can I create a Word document in SharePoint instead of OneDrive?

While the provided analysis focuses on OneDrive operations (/me/drive/... endpoints), the Microsoft Graph API supports SharePoint document libraries through different endpoint paths. The src/lib/graphClient.ts implementation would need to target site-specific drive IDs rather than the default user drive to support SharePoint document creation.

How do I use a template when creating a new Word document?

Use the --template flag followed by the path to an existing .docx file in your OneDrive. For example: office-cli word:create --title "NewDoc.docx" --template "/Templates/Standard.docx". The command checks for this flag in src/commands/word/create.ts and calls the copyTemplate utility function rather than creating a blank file object.

Where does OfficeCLI store authentication tokens?

According to the architecture outlined in src/lib/auth.ts, OfficeCLI implements token caching to avoid repeated authentication prompts. The tokens are stored locally after initial Azure AD authentication and refreshed automatically by the getGraphClient() function in src/lib/graphClient.ts when API calls are made.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}