# Vertopal CLI
Vertopal CLI is a small yet powerful utility that allows you to convert digital files into various formats using the [Vertopal public API](https://www.vertopal.com/en/developer/api).
You can use Vertopal CLI by either *terminal commands* or *importing as a Python package*.
## Installing Vertopal CLI
Vertopal CLI is available on [PyPI](https://pypi.org/project/vertopal/):
```bash
python -m pip install vertopal
```
You can also download the most recent version of Vertopal CLI binaries for **macOS**, **Windows**, and **Linux** from the [releases page](https://github.com/vertopal/vertopal-cli/releases/latest) or the [product page](https://www.vertopal.com/en/product/cli).
### Installer
An automatic installer is available for each different platform. It will run an install script that downloads and copy Vertopal CLI binaries to the correct location.
Using macOS Terminal:
```bash
curl https://run.vertopal.com/cli/macos | bash
```
On Windows using PowerShell:
```bash
(curl https://run.vertopal.com/cli/windows).Content | iex
```
> [!TIP]
> If you are getting any `UnauthorizedAccess` error, then start Windows PowerShell with the "Run as administrator" option and run `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine`.
>
> Now rerun the above installation command. To change the [*Execution Policies*](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies) to its default, you can run `Set-ExecutionPolicy -ExecutionPolicy Default -Scope LocalMachine`.
Using Linux Terminal:
```bash
curl https://run.vertopal.com/cli/linux | bash
```
## Using Vertopal CLI
Starting with **Vertopal CLI v2.0** the package ships with a public default credential (app: `free`, token: `FREE-TOKEN`) so you can try the CLI and Python client without creating an account. This default credential is suitable for personal testing and evaluation and is subject to daily rate limits; if you intend to run production workloads or to exceed the free limits, [obtain a private Application ID and Security Token](http://www.vertopal.com/en/account/api/app/new) from your Vertopal account and configure them (see the [configuration section](#setting-app-id-and-security-token-optional)).
Converting files from the terminal is simple:
```bash
vertopal convert report.pdf --to docx
```
### Bulk Conversion Support
Vertopal CLI supports **bulk conversion**, allowing you to process multiple files, entire directories, or complex patterns in a single command. You can combine:
- Brace expansion: `{a,b}`, `{1..5}`
- Bracket expansion: `[abc]`, `[0-9]`
- Wildcards: `*`, `?`
- Recursive globs: `**/*`
- Exclusion filters: `--exclude` for fine‑grained control
- Date filtering: `--modified-since` for time‑based selection
Here are some real‑world examples:
```bash
# Convert quarterly reports for multiple years
vertopal convert report_{2022,2023,2024}_{Q1,Q2,Q3,Q4}.pdf --to txt
# Convert files in multiple folders with different extensions
vertopal convert ./{docs,src,tests}/**/*.{txt,md,pdf} --to html
# Convert numbered chapters with exclusions
vertopal convert chapter_{01..20}.docx --exclude "chapter_{05,10,15}.docx" --to txt
# Convert all PDFs recursively, excluding drafts and backups
vertopal convert ./**/*.pdf --exclude "*draft*" "*backup*" --to txt
# Convert only files modified since a given date
vertopal convert **/*.docx --modified-since 2025-01-01 --to pdf
```
For the complete pattern syntax and advanced usage scenarios, see the [Enhanced Pattern Matching Guide](docs/cli/patterns.md).
### Streaming Conversions (stdin/stdout)
Vertopal CLI can also read from standard input and write to standard output, making
it easy to integrate into pipelines or generate files on the fly without intermediate
storage.
```bash
# Create a PDF from Markdown text provided via stdin
echo "Vertopal is **AWESOME!**" | vertopal convert - --from md --to pdf --output awesome.pdf
```
### Setting App ID and Security Token (optional)
If you have a private Application ID and Security Token (recommended for production), configure them in the user configuration file.
Set credentials using the `vertopal config` subcommand:
```bash
vertopal config api.app "your-app-id" api.token "your-security-token"
```
After setting a private credential, the CLI and Python client will use it for authenticated requests. If you do not set credentials, the bundled public credential will be used by default.
### Importing as Python package
Importing vertopal as a Python package makes it easy to implement file conversions in your projects.
The following code illustrates [GIF to APNG](https://www.vertopal.com/en/convert/gif-to-apng) conversion using the Vertopal Python package.
```python
from vertopal import Converter
from vertopal.io import FileInput, FileOutput
source = FileInput("./MickeyMouse.gif")
sink = FileOutput("./MickeyMouse.apng")
converter = Converter()
conversion = converter.convert(
readable=source,
writable=sink,
output_format="apng",
)
conversion.wait()
if conversion.successful():
conversion.download()
```
Raw data
{
"_id": null,
"home_page": "https://github.com/vertopal/vertopal-cli",
"name": "vertopal",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.9",
"maintainer_email": null,
"keywords": "convert, file, vertopal, api, converter",
"author": "Vertopal",
"author_email": "Vertopal <contact@vertopal.com>",
"download_url": "https://files.pythonhosted.org/packages/19/c3/a365f1ddc3cd17759539c506b8dc02464d5a298a2776bf2b530b15b8451d/vertopal-2.0.3.tar.gz",
"platform": null,
"description": "# Vertopal CLI\n\nVertopal CLI is a small yet powerful utility that allows you to convert digital files into various formats using the [Vertopal public API](https://www.vertopal.com/en/developer/api).\n\nYou can use Vertopal CLI by either *terminal commands* or *importing as a Python package*.\n\n## Installing Vertopal CLI\n\nVertopal CLI is available on [PyPI](https://pypi.org/project/vertopal/):\n\n```bash\npython -m pip install vertopal\n```\n\nYou can also download the most recent version of Vertopal CLI binaries for **macOS**, **Windows**, and **Linux** from the [releases page](https://github.com/vertopal/vertopal-cli/releases/latest) or the [product page](https://www.vertopal.com/en/product/cli).\n\n### Installer\n\nAn automatic installer is available for each different platform. It will run an install script that downloads and copy Vertopal CLI binaries to the correct location.\n\nUsing macOS Terminal:\n\n```bash\ncurl https://run.vertopal.com/cli/macos | bash\n```\n\nOn Windows using PowerShell:\n\n```bash\n(curl https://run.vertopal.com/cli/windows).Content | iex\n```\n\n> [!TIP]\n> If you are getting any `UnauthorizedAccess` error, then start Windows PowerShell with the \"Run as administrator\" option and run `Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope LocalMachine`.\n>\n> Now rerun the above installation command. To change the [*Execution Policies*](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_execution_policies) to its default, you can run `Set-ExecutionPolicy -ExecutionPolicy Default -Scope LocalMachine`.\n\nUsing Linux Terminal:\n\n```bash\ncurl https://run.vertopal.com/cli/linux | bash\n```\n\n## Using Vertopal CLI\n\nStarting with **Vertopal CLI v2.0** the package ships with a public default credential (app: `free`, token: `FREE-TOKEN`) so you can try the CLI and Python client without creating an account. This default credential is suitable for personal testing and evaluation and is subject to daily rate limits; if you intend to run production workloads or to exceed the free limits, [obtain a private Application ID and Security Token](http://www.vertopal.com/en/account/api/app/new) from your Vertopal account and configure them (see the [configuration section](#setting-app-id-and-security-token-optional)).\n\nConverting files from the terminal is simple:\n\n```bash\nvertopal convert report.pdf --to docx\n```\n\n### Bulk Conversion Support\n\nVertopal CLI supports **bulk conversion**, allowing you to process multiple files, entire directories, or complex patterns in a single command. You can combine:\n\n- Brace expansion: `{a,b}`, `{1..5}`\n- Bracket expansion: `[abc]`, `[0-9]`\n- Wildcards: `*`, `?`\n- Recursive globs: `**/*`\n- Exclusion filters: `--exclude` for fine\u2011grained control\n- Date filtering: `--modified-since` for time\u2011based selection\n\nHere are some real\u2011world examples:\n\n```bash\n# Convert quarterly reports for multiple years\nvertopal convert report_{2022,2023,2024}_{Q1,Q2,Q3,Q4}.pdf --to txt\n\n# Convert files in multiple folders with different extensions\nvertopal convert ./{docs,src,tests}/**/*.{txt,md,pdf} --to html\n\n# Convert numbered chapters with exclusions\nvertopal convert chapter_{01..20}.docx --exclude \"chapter_{05,10,15}.docx\" --to txt\n\n# Convert all PDFs recursively, excluding drafts and backups\nvertopal convert ./**/*.pdf --exclude \"*draft*\" \"*backup*\" --to txt\n\n# Convert only files modified since a given date\nvertopal convert **/*.docx --modified-since 2025-01-01 --to pdf\n```\n\nFor the complete pattern syntax and advanced usage scenarios, see the [Enhanced Pattern Matching Guide](docs/cli/patterns.md).\n\n### Streaming Conversions (stdin/stdout)\n\nVertopal CLI can also read from standard input and write to standard output, making\nit easy to integrate into pipelines or generate files on the fly without intermediate\nstorage.\n\n```bash\n# Create a PDF from Markdown text provided via stdin\necho \"Vertopal is **AWESOME!**\" | vertopal convert - --from md --to pdf --output awesome.pdf\n```\n\n### Setting App ID and Security Token (optional)\n\nIf you have a private Application ID and Security Token (recommended for production), configure them in the user configuration file.\n\nSet credentials using the `vertopal config` subcommand:\n\n```bash\nvertopal config api.app \"your-app-id\" api.token \"your-security-token\"\n```\n\nAfter setting a private credential, the CLI and Python client will use it for authenticated requests. If you do not set credentials, the bundled public credential will be used by default.\n\n### Importing as Python package\n\nImporting vertopal as a Python package makes it easy to implement file conversions in your projects.\n\nThe following code illustrates [GIF to APNG](https://www.vertopal.com/en/convert/gif-to-apng) conversion using the Vertopal Python package.\n\n```python\nfrom vertopal import Converter\nfrom vertopal.io import FileInput, FileOutput\n\nsource = FileInput(\"./MickeyMouse.gif\")\nsink = FileOutput(\"./MickeyMouse.apng\")\n\nconverter = Converter()\nconversion = converter.convert(\n readable=source,\n writable=sink,\n output_format=\"apng\",\n)\nconversion.wait()\nif conversion.successful():\n conversion.download()\n```\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Convert your files in terminal using Vertopal API",
"version": "2.0.3",
"project_urls": {
"Bug Tracker": "https://github.com/vertopal/vertopal-cli/issues",
"Funding": "https://www.vertopal.com/en/donate",
"Homepage": "https://www.vertopal.com",
"Source": "https://github.com/vertopal/vertopal-cli"
},
"split_keywords": [
"convert",
" file",
" vertopal",
" api",
" converter"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "20ce92ec28d0ac3a33d4cbfc4eaa37f3d93beba3bd3a25e36b0dd27d5968783c",
"md5": "f0ff99292bf97a13298a80e9d268abc6",
"sha256": "cd75eae10acdc3e5b0f5c19bd8290c40f4cbea41d95003209937baf78653e2e7"
},
"downloads": -1,
"filename": "vertopal-2.0.3-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f0ff99292bf97a13298a80e9d268abc6",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.9",
"size": 73059,
"upload_time": "2025-09-01T15:54:16",
"upload_time_iso_8601": "2025-09-01T15:54:16.940007Z",
"url": "https://files.pythonhosted.org/packages/20/ce/92ec28d0ac3a33d4cbfc4eaa37f3d93beba3bd3a25e36b0dd27d5968783c/vertopal-2.0.3-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "19c3a365f1ddc3cd17759539c506b8dc02464d5a298a2776bf2b530b15b8451d",
"md5": "41197f26b2e51e0aa75c7ddc44e7f7ca",
"sha256": "937d3eb011c9578ef30a330b6afb85708f0269ef36eb58696e2cc7f39eedba39"
},
"downloads": -1,
"filename": "vertopal-2.0.3.tar.gz",
"has_sig": false,
"md5_digest": "41197f26b2e51e0aa75c7ddc44e7f7ca",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.9",
"size": 60836,
"upload_time": "2025-09-01T15:54:17",
"upload_time_iso_8601": "2025-09-01T15:54:17.997859Z",
"url": "https://files.pythonhosted.org/packages/19/c3/a365f1ddc3cd17759539c506b8dc02464d5a298a2776bf2b530b15b8451d/vertopal-2.0.3.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-09-01 15:54:17",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "vertopal",
"github_project": "vertopal-cli",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"requirements": [
{
"name": "requests",
"specs": [
[
">=",
"2.28.2"
]
]
}
],
"lcname": "vertopal"
}
JSON
