apdf-cloud-cli 0.4.0

CLI and MCP server tools for Aspose PDF Cloud

APDF Cloud CLI + MCP Tools

APDF Cloud CLI exposes Aspose PDF Cloud storage and PDF operations through both a command-line interface and an MCP server.

Installation

Install from PyPI:

python -m pip install apdf-cloud-cli

Check that the CLI is available:

apdf-cloud-cli --help
apdf --help

For local development from a checkout:

python -m pip install -e ".[dev]"

Configuration

Set credentials before running CLI commands or the MCP server. The easiest local setup path is:

apdf auth login
apdf auth status
apdf auth test

You can also set credentials directly in your shell:

$env:ASPOSE_CLIENT_ID = "your-client-id"
$env:ASPOSE_CLIENT_SECRET = "your-client-secret"

Optional environment variables:

• ASPOSE_STORAGE_NAME: default Aspose storage name.
• ASPOSE_BASE_URL: alternate Aspose PDF Cloud base URL.
• ASPOSE_SELF_HOST: set to 1, true, yes, or on for self-hosted use.

You can also create a local .env file. See .env.example for a template. Environment variables take precedence over .env values.

CLI Usage

The canonical executable is apdf-cloud-cli. A shorter apdf alias is also installed for convenience.

apdf-cloud-cli storage list /
apdf-cloud-cli auth status
apdf-cloud-cli auth test
apdf-cloud-cli storage upload .\sample.pdf /sample.pdf
apdf-cloud-cli storage download /sample.pdf .\sample.pdf
apdf-cloud-cli pdf merge merged.pdf /a.pdf /b.pdf /c.pdf
apdf-cloud-cli pdf merge merged.pdf --from-folder /contracts
apdf-cloud-cli pdf extract-text sample.pdf --output sample.txt
apdf-cloud-cli pdf extract-tables sample.pdf --output tables.json
apdf-cloud-cli pdf extract-tables sample.pdf --pages 1,3,4-7,10 --output tables.json
apdf-cloud-cli mcp serve

MCP Usage

After installing the package, configure your MCP client to launch:

apdf-cloud-cli mcp serve

Codex MCP configuration examples are available in docs/mcp-config.md, with a copy-pasteable helper at examples/codex-mcp-config.toml.

Codex Prompts

Sample prompts for using this MCP server with Codex are in docs/codex-prompts.md.

Install as an Agent Skill

The package includes an apdf-cloud-mcp skill for Codex and Claude Code. Install the package first, then install the bundled skill:

python -m pip install apdf-cloud-cli
apdf-cloud-cli skill install codex
apdf-cloud-cli skill install claude-code

For Claude Code project-local installation:

apdf-cloud-cli skill install claude-code --project

Use --force to replace an existing installed copy. More details are in docs/agent-skill.md.

Development

Run the default unit test suite:

python -m pytest -q

Run live Aspose Cloud smoke tests only when you intentionally want to call the real API:

$env:ASPOSE_RUN_LIVE_TESTS = "1"
python -m pytest -q -m live

More live-test setup notes are in docs/live-tests.md.

Build and validate the package distributions:

python -m build
python -m twine check dist/*

Security

Never commit real credentials. Keep .env local, prefer short-lived environment variables in CI, and avoid pasting secrets into issue reports, test output, logs, or prompts. See docs/security.md.

Publishing

Publishing is handled by GitHub Actions with PyPI trusted publishing.

1. In PyPI, add a trusted publisher for repository andruhovski/apdf-tools, workflow publish.yml, environment pypi, and project name apdf-cloud-cli.
2. Update the version in pyproject.toml and src/apdf_cloud_cli/__init__.py.
3. Push a matching version tag, for example:

git tag v0.2.0
git push origin v0.2.0

Stage 2 Roadmap

• Split PDF files
• Extract images from PDF files