Skip to content

Commit 720a184

Browse files
vladimir-litvinchikvladimir-litvinchik
committed
Cleanup and new documentation page for command line interface shipped in 26.5
1 parent 896b52b commit 720a184

6 files changed

Lines changed: 171 additions & 34 deletions

File tree

‎python-net/getting-started/command-line-interface.md‎

Lines changed: 153 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,153 @@
1+
---
2+
id: command-line-interface
3+
url: conversion/python-net/getting-started/command-line-interface
4+
title: Command Line Interface
5+
linkTitle: Command Line Interface
6+
second_title: Convert documents from the terminal with the groupdocs-conversion CLI
7+
weight: 6
8+
keywords: command line, CLI, terminal, groupdocs-conversion, convert documents, shell, pipeline, CI, batch conversion, document info, supported formats, GroupDocs.Conversion, python
9+
description: "Convert documents straight from the terminal with the groupdocs-conversion command-line tool — no Python script required. Inspect documents, list supported formats, and apply a license, all from the shell."
10+
productName: GroupDocs.Conversion for Python via .NET
11+
hideChildren: False
12+
toc: True
13+
---
14+
15+
Installing the `groupdocs-conversion-net` package also puts a `groupdocs-conversion` console script on your `PATH`. It is a thin wrapper over the Python API, built for the cases where spinning up a Python script is overkill — shell pipelines, Make rules, CI steps, and one-off conversions.
16+
17+
## Prerequisites
18+
19+
The CLI ships inside the package, so no extra installation is needed. Make sure `groupdocs-conversion-net` is installed (see the [Quick Start Guide]({{< ref "conversion/python-net/getting-started/quick-start-guide.md" >}})), then verify the console script is available:
20+
21+
```bash
22+
groupdocs-conversion --version
23+
```
24+
25+
You should see the package version printed, for example `groupdocs-conversion 26.5.0`.
26+
27+
{{< alert style="info" >}}
28+
If the `groupdocs-conversion` command is not found, the package's script directory may not be on your `PATH`. You can always invoke the CLI through the Python module form instead: `python -m groupdocs.conversion`. The two are equivalent.
29+
{{< /alert >}}
30+
31+
## Commands
32+
33+
The CLI exposes four subcommands. Run `groupdocs-conversion --help` for the full flag listing, or `groupdocs-conversion <command> --help` for a specific subcommand.
34+
35+
### convert
36+
37+
Convert a document to another format. The target format is inferred from the output file extension; pass `--format` to override it.
38+
39+
```bash
40+
# Extension picks the target format
41+
groupdocs-conversion convert business-plan.docx business-plan.pdf
42+
43+
# Override the format when the output name doesn't carry a usable extension
44+
groupdocs-conversion convert business-plan.docx output.bin --format pdf
45+
46+
# Convert a single page (1-indexed) — useful for raster targets
47+
groupdocs-conversion convert annual-review.pdf page1.png --page 1 --count 1
48+
49+
# Open a password-protected source
50+
groupdocs-conversion convert protected.docx protected.pdf --password "secret"
51+
```
52+
53+
| Option | Description |
54+
| :- | :- |
55+
| `--format` | Target format token (overrides the output extension). |
56+
| `--password` | Password for a protected source document. |
57+
| `--page` | First page to convert, 1-indexed. |
58+
| `--count` | Number of pages to convert. |
59+
60+
On success the command prints the output path and exits with code `0`.
61+
62+
### info
63+
64+
Print basic information about a document — format, size, page count, and creation date when available.
65+
66+
```bash
67+
groupdocs-conversion info annual-review.pdf
68+
```
69+
70+
```text
71+
format: pdf
72+
size: 291788
73+
pages_count: 10
74+
```
75+
76+
Use `--password` for protected sources.
77+
78+
### list-formats
79+
80+
List every target format the engine can produce for a given input document, split into primary and secondary targets.
81+
82+
```bash
83+
groupdocs-conversion list-formats business-plan.docx
84+
```
85+
86+
Use `--password` for protected sources.
87+
88+
### list-all-formats
89+
90+
Print the full source-to-target conversion matrix known to the engine — every input format and the targets it can be converted to.
91+
92+
```bash
93+
groupdocs-conversion list-all-formats
94+
```
95+
96+
This command takes no input file.
97+
98+
## Global options
99+
100+
These options apply to every command:
101+
102+
| Option | Description |
103+
| :- | :- |
104+
| `--license PATH` | Apply a license file before running the command. |
105+
| `--version` | Print the CLI version and exit. |
106+
| `--help` | Show usage help and exit. |
107+
108+
Apply a license up front by placing `--license` before the subcommand:
109+
110+
```bash
111+
groupdocs-conversion --license GroupDocs.Conversion.lic convert business-plan.docx business-plan.pdf
112+
```
113+
114+
{{< alert style="info" >}}
115+
The CLI also honours the `GROUPDOCS_LIC_PATH` environment variable — if it is set, the license is applied automatically and you can omit `--license`. See the [Licensing]({{< ref "conversion/python-net/getting-started/licensing-and-subscription.md" >}}) topic for details.
116+
{{< /alert >}}
117+
118+
## Format tokens
119+
120+
`convert` maps the output extension — or the `--format` value, lowercased — to the matching convert options and file type. The supported tokens are:
121+
122+
| Category | Tokens |
123+
| :- | :- |
124+
| PDF | `pdf` |
125+
| Word processing | `doc`, `docx`, `rtf`, `odt`, `txt`, `md` |
126+
| Spreadsheet | `xls`, `xlsx`, `xlsm`, `ods`, `csv`, `tsv` |
127+
| Presentation | `ppt`, `pptx`, `pptm`, `odp` |
128+
| Web | `html`, `htm`, `mhtml` |
129+
| Image | `jpg`, `jpeg`, `png`, `bmp`, `gif`, `tiff`, `tif`, `webp`, `svg` |
130+
| eBook | `epub`, `mobi`, `azw3` |
131+
132+
An unknown token causes the command to exit with code `2` and print the list of accepted tokens.
133+
134+
## Exit codes
135+
136+
| Code | Meaning |
137+
| :- | :- |
138+
| `0` | Success. |
139+
| `2` | User error — unknown format token or missing input file. |
140+
| `1` | Runtime error — the underlying .NET exception message is printed to standard error. |
141+
142+
These codes make the CLI easy to branch on in shell scripts and CI pipelines.
143+
144+
## When to use the Python API instead
145+
146+
The CLI covers the common single-document conversion cases. For anything beyond that — per-page callbacks, in-memory streams, watermark, font, or cell-range options, and multi-document container hierarchies — use the Python API directly. It exposes a richer surface than the CLI flags. See the [Developer Guide]({{< ref "conversion/python-net/developer-guide" >}}) for the full feature set.
147+
148+
## Next Steps
149+
150+
- [Quick Start Guide]({{< ref "conversion/python-net/getting-started/quick-start-guide.md" >}}): Convert your first document with the Python API.
151+
- [Supported File Formats]({{< ref "conversion/python-net/getting-started/supported-document-formats.md" >}}): Review the full list of supported file types.
152+
- [Licensing]({{< ref "conversion/python-net/getting-started/licensing-and-subscription.md" >}}): Apply a license to remove evaluation limits.
153+
- [Technical Support]({{< ref "conversion/python-net/technical-support" >}}): Contact support if you encounter issues.

‎python-net/getting-started/how-to-run-examples.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ id: how-to-run-examples
33
url: conversion/python-net/how-to-run-examples
44
title: How to Run Examples
55
linkTitle: How to Run Examples
6-
weight: 7
6+
weight: 8
77
description: "Clone the GitHub examples repository, install dependencies into a virtual environment, optionally apply a license, and run every documented example end to end — locally, inside Docker, or on GitHub Actions."
88
keywords: run examples, examples repository, github, docker, dockerfile, CI, GitHub Actions, venv, virtual environment, run_all_examples, GROUPDOCS_LIC_PATH, GroupDocs.Conversion, python
99
productName: GroupDocs.Conversion for Python via .NET

‎python-net/getting-started/installation.md‎

Lines changed: 7 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -5,13 +5,13 @@ title: Installation
55
linkTitle: Installation
66
weight: 4
77
description: "Install GroupDocs.Conversion for Python via .NET on Windows, Linux, or macOS — from PyPI or from a pre-downloaded wheel, including Intel and Apple Silicon builds."
8-
keywords: install, installation, pip, pypi, wheel, whl, Windows, Linux, macOS, Apple Silicon, manylinux, musllinux, requirements.txt, GroupDocs.Conversion, python
8+
keywords: install, installation, pip, pypi, wheel, whl, Windows, Linux, macOS, Apple Silicon, manylinux, requirements.txt, GroupDocs.Conversion, python
99
productName: GroupDocs.Conversion for Python via .NET
1010
hideChildren: False
1111
toc: True
1212
---
1313

14-
GroupDocs.Conversion for Python via .NET is distributed as a pre-built wheel on [PyPI](https://pypi.org/project/groupdocs-conversion-net/). The PyPI index hosts a separate wheel for each supported platform pair, and `pip` picks the correct one automatically.
14+
GroupDocs.Conversion for Python via .NET is distributed as a pre-built wheel on [PyPI](https://pypi.org/project/groupdocs-conversion-net/). The PyPI index hosts a separate wheel for each supported platform, and `pip` picks the correct one automatically.
1515

1616
Before installing, confirm your environment matches the supported platforms and Python versions listed in the [System Requirements]({{< ref "conversion/python-net/getting-started/system-requirements.md" >}}) topic.
1717

@@ -48,7 +48,7 @@ Installing collected packages: groupdocs-conversion-net
4848
Successfully installed groupdocs-conversion-net-26.3
4949
```
5050

51-
The wheel file name will include a platform suffix that matches your operating system — for example `manylinux_2_17_x86_64` on Ubuntu/Debian, `macosx_11_0_arm64` on Apple Silicon, or `win_amd64` on 64-bit Windows.
51+
The wheel file name will include a platform suffix that matches your operating system — for example `manylinux1_x86_64` on Ubuntu/Debian, `macosx_11_0_arm64` on Apple Silicon, or `win_amd64` on 64-bit Windows.
5252

5353
## Add the Package to `requirements.txt`
5454

@@ -69,11 +69,9 @@ pip install -r requirements.txt
6969
If your build environment cannot reach PyPI, download the appropriate wheel from the [GroupDocs Releases website](https://releases.groupdocs.com/conversion/python-net/) and install it locally. The following wheels are published for each release:
7070

7171
- **Windows 64-bit**: file name ends with `win_amd64.whl`
72-
- **Windows 32-bit**: file name ends with `win32.whl`
73-
- **Linux x64 (glibc)**: `manylinux_2_17_x86_64.manylinux2014_x86_64.whl`
74-
- **Linux musl (Alpine)**: `musllinux_1_2_x86_64.whl`
75-
- **macOS Apple Silicon**: `macosx_11_0_arm64.whl`
76-
- **macOS Intel**: `macosx_10_14_x86_64.whl`
72+
- **Linux x64 (glibc)**: file name ends with `manylinux1_x86_64.whl`
73+
- **macOS Apple Silicon**: file name ends with `macosx_11_0_arm64.whl`
74+
- **macOS Intel**: file name ends with `macosx_10_14_x86_64.whl`
7775

7876
Place the downloaded wheel into your project folder, then install it:
7977

@@ -83,19 +81,9 @@ Place the downloaded wheel into your project folder, then install it:
8381
py -m pip install groupdocs_conversion_net-26.3-py3-none-win_amd64.whl
8482
```
8583
{{< /tab >}}
86-
{{< tab "Windows (32-bit)" >}}
87-
```ps
88-
py -m pip install groupdocs_conversion_net-26.3-py3-none-win32.whl
89-
```
90-
{{< /tab >}}
9184
{{< tab "Linux (glibc)" >}}
9285
```bash
93-
python3 -m pip install groupdocs_conversion_net-26.3-py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl
94-
```
95-
{{< /tab >}}
96-
{{< tab "Linux (musl)" >}}
97-
```bash
98-
python3 -m pip install groupdocs_conversion_net-26.3-py3-none-musllinux_1_2_x86_64.whl
86+
python3 -m pip install groupdocs_conversion_net-26.3-py3-none-manylinux1_x86_64.whl
9987
```
10088
{{< /tab >}}
10189
{{< tab "macOS (Apple Silicon)" >}}

‎python-net/getting-started/licensing-and-subscription.md‎

Lines changed: 2 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -3,17 +3,15 @@ id: licensing-and-subscription
33
url: conversion/python-net/licensing-and-subscription
44
title: Licensing
55
linkTitle: Licensing
6-
weight: 6
6+
weight: 7
77
description: "Evaluate, apply, and manage licenses for GroupDocs.Conversion for Python via .NET — free trial with limitations, 30-day temporary license, file and stream license loading, and metered licensing."
88
keywords: license, licensing, free trial, temporary license, metered license, GROUPDOCS_LIC_PATH, set license from file, set license from stream, evaluation limitations, GroupDocs.Conversion
99
productName: GroupDocs.Conversion for Python via .NET
1010
hideChildren: False
1111
toc: True
1212
---
1313

14-
To help you quickly explore library and its features, GroupDocs.Conversion provides a Free Trial and a 30-day Temporary License for evaluation, as well as various purchase plans.
15-
16-
Sometimes, to get familiar with the system quickly, you may want to dive into the code right away. To make this easier, GroupDocs.Conversion offers a Free Trial and a 30-day Temporary License for evaluation, along with various purchase plans.
14+
To help you quickly explore the library and its features, GroupDocs.Conversion provides a Free Trial and a 30-day Temporary License for evaluation, as well as various purchase plans.
1715

1816
{{< alert style="info" >}}
1917
Please note that general policies and practices guide you on evaluating, licensing, and purchasing our products. See the [Purchase Policies and FAQ](https://purchase.groupdocs.com/policies/) section for details.

‎python-net/getting-started/quick-start-guide.md‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -97,7 +97,7 @@ Successfully installed groupdocs-conversion-net-*
9797

9898
## Example 1: Convert document
9999

100-
To quickly test the library, let’s convert a DOCX file to PDF. You can also download the app that we're going to buid [here](/conversion/python-net/_sample_files/getting-started/quick-start-guide/convert_docx_to_pdf.zip).
100+
To quickly test the library, let’s convert a DOCX file to PDF. You can also download the app that we're going to build [here](/conversion/python-net/_sample_files/getting-started/quick-start-guide/convert_docx_to_pdf.zip).
101101

102102
{{< tabs "demo_app_convert_docx_to_pdf">}}
103103
{{< tab "convert_docx_to_pdf.py" >}}
@@ -178,7 +178,7 @@ After running the app you can deactivate virtual environment by executing `deact
178178

179179
## Example 2: Convert document pages
180180

181-
In this example we'll convert PDF document pages to PNG. You can download the app that we're going to buid [here](/conversion/python-net/_sample_files/getting-started/quick-start-guide/convert_pdf_pages_to_png.zip).
181+
In this example we'll convert PDF document pages to PNG. You can download the app that we're going to build [here](/conversion/python-net/_sample_files/getting-started/quick-start-guide/convert_pdf_pages_to_png.zip).
182182

183183
{{< tabs "demo_app_convert_pdf_pages_to_png">}}
184184
{{< tab "convert_pdf_pages_to_png.py" >}}
@@ -274,7 +274,7 @@ After running the app you can deactivate virtual environment by executing `deact
274274

275275
## Example 3: Convert files in archive
276276

277-
In this example we'll convert the contents of a ZIP archive to PDF. GroupDocs.Conversion opens the archive, converts the files inside, and produces a single consolidated PDF that contains every converted document. You can download the app that we're going to buid [here](/conversion/python-net/_sample_files/getting-started/quick-start-guide/convert_files_in_archive.zip).
277+
In this example we'll convert the contents of a ZIP archive to PDF. GroupDocs.Conversion opens the archive, converts the files inside, and produces a single consolidated PDF that contains every converted document. You can download the app that we're going to build [here](/conversion/python-net/_sample_files/getting-started/quick-start-guide/convert_files_in_archive.zip).
278278

279279
{{< tabs "demo_app_convert_files_in_archive">}}
280280
{{< tab "convert_files_in_archive.py" >}}
@@ -357,5 +357,5 @@ After running the app you can deactivate virtual environment by executing `deact
357357

358358
After completing the basics, explore additional resources to enhance your usage:
359359
- [Supported File Formats]({{< ref "conversion/python-net/getting-started/supported-document-formats.md" >}}): Review the full list of supported file types.
360-
- [Licensing]({{< ref "conversion/python-net/getting-started/licensing-and-subscription.md" >}}): Check details on licening and evaluation.
360+
- [Licensing]({{< ref "conversion/python-net/getting-started/licensing-and-subscription.md" >}}): Check details on licensing and evaluation.
361361
- [Technical Support]({{< ref "conversion/python-net/technical-support" >}}): Contact support for assistance if you encounter issues.

‎python-net/getting-started/system-requirements.md‎

Lines changed: 4 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -21,13 +21,13 @@ GroupDocs.Conversion for Python via .NET runs on Windows, Linux, and macOS. Choo
2121

2222
### Windows
2323

24-
* Microsoft Windows 10 (x64, x86)
24+
* Microsoft Windows 10 (x64)
2525
* Microsoft Windows 11 (x64)
2626
* Microsoft Windows Server 2016 and later
2727

2828
### Linux
2929

30-
* Ubuntu 20.04+, Debian 11+, CentOS 8+, Fedora 36+, Alpine 3.16+
30+
* Ubuntu 20.04+, Debian 11+, CentOS 8+, Fedora 36+ (glibc-based distributions)
3131

3232
### macOS
3333

@@ -58,14 +58,12 @@ GroupDocs.Conversion for Python via .NET is distributed via [PyPI](https://pypi.
5858
pip install groupdocs-conversion-net
5959
```
6060

61-
The PyPI index hosts one wheel per platform pair:
61+
The PyPI index hosts one wheel per platform:
6262

6363
| Platform | Wheel suffix |
6464
| --- | --- |
6565
| Windows 64-bit | `py3-none-win_amd64.whl` |
66-
| Windows 32-bit | `py3-none-win32.whl` |
67-
| Linux x64 (glibc) | `py3-none-manylinux_2_17_x86_64.manylinux2014_x86_64.whl` |
68-
| Linux musl (Alpine) | `py3-none-musllinux_1_2_x86_64.whl` |
66+
| Linux x64 (glibc) | `py3-none-manylinux1_x86_64.whl` |
6967
| macOS Apple Silicon | `py3-none-macosx_11_0_arm64.whl` |
7068
| macOS Intel | `py3-none-macosx_10_14_x86_64.whl` |
7169

0 commit comments

Comments
 (0)