# msword-cli

**Repository Path**: anderson2/msword-cli

## Basic Information

- **Project Name**: msword-cli
- **Description**: No description available
- **Primary Language**: Unknown
- **License**: BSD-2-Clause
- **Default Branch**: master
- **Homepage**: None
- **GVP Project**: No

## Statistics

- **Stars**: 0
- **Forks**: 0
- **Created**: 2026-06-06
- **Last Updated**: 2026-06-06

## Categories & Tags

**Categories**: Uncategorized

**Tags**: None

## README

==========
MSWord-CLI
==========
-------------------------------------------
A Command Line Interface for Microsoft Word
-------------------------------------------

.. contents:: Table of Contents
   :backlinks: top

Summary
=======

.. default-role:: code

MSWord-CLI allows you to control Microsoft Word from the command line and/or automate
it from batch or PowerShell scripts. Among other things, you may create, open, print,
export, save, and close Word documents. Note that MSWord-CLI does not actually edit the 
content of any documents. That is beyond the scope of this project.

.. warning::
	This is **Pre-Alpha** software which is in active development. The various subcommands, options,
	and arguments are subject to change without notice and may not be sufficiently tested.

	All development has been done on Windows 7 with MS Office 2013. `Bug reports`_ are welcome on any 
	system, although the reporter may need to do much of the work on other systems and/or versions.

.. _`Bug reports`: https://github.com/waylan/msword-cli/issues/new

Installation
============

Installing the latest development code
--------------------------------------

If you would like to use the bleeding edge, you can install directly from the the Github Repo. 
However, be aware that this code is not guaranteed to be stable or even run. It is recommended
that stable releases be installed instead. Proceed at your own risk.

From the command line execute the following commands as an Administrator:

.. code:: bash

	> git clone https://github.com/waylan/msword-cli.git
	> cd msword-cli
	> python setup.py install

These instructions assume that `Git for Windows`_, `Python`_ and `Setuptools`_ are already installed 
on your system. 

.. _`Git for Windows`: http://www.git-scm.com/downloads

Making the `msw` command available on your PATH
-----------------------------------------------

If you are using Python version 3.4 and you enabled the "Add Python.exe to Path” feature
during installation (off by default), you can skip this section.

Generaly, when running Python, or python scripts from the command line you would need to inlcude the
full path to the script. However, with a little configuration, Windows will find your scripts
without needing to include the full path to the script. You need to tell Windows where the Python
executable (`python.exe`) and your scripts (`msw.exe`) can be found by inlcuding those directories
in the `PATH` environment variable. Therefore, assuming you are using Python version 2.7, add the 
following to the `PATH` environment variable (with no spaces):

.. code::

    C:\Python27\;C:\Python27\Scripts\

If you are using a differant version of Python, or if you have installed Python in a non-standard 
location, you will need to adjust those paths accordingly. See the `Python Guide`_ for more information.

If you are using the `Python Launcher`_ (`py.exe`), you will not need to add the path to `python.exe` to
the `PATH` environment variable, but you will still need to add the `Scripts` directory, which is where
`msw.exe` gets installed.

.. _`Python Guide`: http://docs.python-guide.org/en/latest/starting/install/win/
.. _`Python Launcher`: https://docs.python.org/3/using/windows.html#python-launcher-for-windows

Basic Usage
===========

To open an existing document:

.. code:: bash

	> msw open mydocument.docx

To print the active (focused) document:

.. code:: bash

	> msw print

To view a list of all open documents:

.. code:: bash

	> msw docs

	Open Documents:

	* [1] mydocument.docx
	  [2] otherdoc.docx

Notice that the asterisk ('`*`') indicates that the document at index 1 (`mydocument.docx`) is the 
currently active document. To change the focus to `otherdoc.docx` (at index 2):

.. code:: bash

	> msw activate 2
	> msw docs

	Open Documents:

	  [1] mydocument.docx
	* [2] otherdoc.docx

Unless otherwise specified all subcommands work on the active document.  

For a complete list of commands and options, run `msw --help` from the command line. For help
with a specific subcommand, run `msw <subcommand> --help`.

Chaining
--------

Subcommands can be chained together. For example, to open a document, print two copies of 
pages 2, 3, 4, and 6 of that document, and then close the document, the following single 
command is all that is needed:

.. code:: bash

	> msw open somedoc.docx print --count 2 --pages "2-4, 6" close

Note that if any options are specified for a subcommand, those options must be specified after
the relevant subcommand and before the next subcommand in the chain. For instance, in the above 
example, `somedoc.docx` is an argument of the `open` subcommand, `--count 2 --pages "2-4, 6"` 
are options for the `print` subcommand and the `close` subcommand has no options or arguments 
defined.

Without command chaining, three separate commands would need to be issued:

.. code:: bash

	> msw open somedoc.docx
	> msw print --count 2 --pages "2-4, 6"
	> msw close

Either method will accomplish the same end result. However, chaining should run a little faster
as the utility only needs to be loaded once for all commands rather than for each command.

Chaining also allows you to run different variations of the same command when that command's
options are mutually exclusive. For example, the `export` subcommand can only accept either
the `--pdf` or the `--xps` flag. If you want to export to both formats, you can chain two
`export` subcommands together :

.. code:: bash

    > msw export --pdf . export --xps .

Note that the dot ('`.`') in the above example specifies the current working directory as the 
export path. All of the common command line paradigms should work out-of-the-box.

Plugins
-------

MSWord-CLI includes support for third-party plugins. A plugin can add additional subcommands
which can be included in a chain. For example, one might desire to have the ability to import
some data to fill a form (perhaps content controls). While it would be unrealistic to try to
include such a script with MSWord-CLI that could meet everyone's needs, there is no reason
why an individual user could not develop a special purpose script to meet her specific needs.

While the script could be written as a standalone script, it would also be convenient to be
able to include the call within a chain. That way, the document could be opened, the data imported,
and then the document could be printed and closed -- all from a single command.

All commands need to be defined as `Click`_ commands. Create a new python file named `msw_import.py`
and define your command:

.. code:: python

    import click

    @click.command('import')
    def imprt():
        ''' Import data. '''
        click.echo('Data is being imported...')

Note that while the command is labeled 'import' (which will be used from the command line), the 
function is named `imprt` so as not to clash with Python's `import` statement. Currently, the 
new command only prints a mesage to the console and exits. Before developing the new command's 
functionality, tell MSWord-CLI about the new subcommand and verify that it can be called. 
To do that, create a second python file named `setup.py` and include a setup script:

.. code:: python

	from setuptools import setup

	setup(
	    name='MSWImportPlugin',
	    version="1",
	    description="Import plugin for MSWord_CLI",
	    py_modules=['msw_import'],
	    entry_points="""
	        [msw.plugin]
	        import=msw_import:imprt
	    """
	)

The key is in the `entry_points`. An entry point was added to the `msw.plugin` group named 'import'
which points to the `imprt` function at its path (`msw_import:imprt`). Additional commands could
be defined from the same Python module. Simply add an additional line to the `entry_points` for 
each one.

Finally, for MSWord-CLI to find the new plugin, it needs to be installed.

.. code:: bash

	> python setup.py install

The above command will do the trick. However, as the plugin isn't finished yet, is would be helpful
to use a special development mode which sets up the path to run the plugin from the source file 
rather than Python's `site-packages` directory. That way, any changes made to the file will 
immediately take effect with no need to reinstall the plugin.

.. code:: bash

	> python setup.py develop

Now that the plugin is installed, test the script:

.. code:: bash
	
	> msw --help

You should find the `import` subcommand listed among the default subcommands in the help messge. 
To ensure that the new subcommand works, try running it:

.. code:: bash
	
	> msw import
	Data is being imported...

As the message was printed to the console, the new `import` subcommand is being called. Now 
the functionally of the `import` subcommand can be fleshed out, which is left as an exercise 
for the reader.

Dependencies
============

MSWord-CLI is built on Python_ and requires that Python version 2.7 or greater be installed
on the system. In addition to the python packages listed below, you must also have a working 
copy of Microsoft Word installed on your system.

Python Packages:

* PyWin32_
* Click_ (version 3)
* Setuptools_

.. _Python: http://python.org/
.. _PyWin32: http://sf.net/projects/pywin32
.. _Click: http://click.pocoo.org/
.. _Setuptools: https://pypi.python.org/pypi/setuptools

License
=======

MSWord-CLI is licensed under the `BSD License`_ as defined in `LICENSE.txt`.

.. _`BSD License`: http://opensource.org/licenses/BSD-2-Clause