Metadata-Version: 2.4
Name: apdf-cloud-cli
Version: 0.2.0
Summary: CLI and MCP server tools for Aspose PDF Cloud
Keywords: aspose,pdf,cli,mcp
Author: Andriy Andruhovski
Author-email: andruhovski@gmail.com
Requires-Python: >=3.11
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Office/Business
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Typing :: Typed
Provides-Extra: dev
Requires-Dist: asposepdfcloud (>=26.4.0,<27.0.0)
Requires-Dist: build (>=1.2.0) ; extra == "dev"
Requires-Dist: mcp (>=1.0.0)
Requires-Dist: pytest (>=8.0.0) ; extra == "dev"
Requires-Dist: pytest-mock (>=3.12.0) ; extra == "dev"
Requires-Dist: rich (>=13.0.0)
Requires-Dist: twine (>=5.0.0) ; extra == "dev"
Requires-Dist: typer (>=0.12.0)
Project-URL: Homepage, https://github.com/andruhovski/apdf-tools
Project-URL: Issues, https://github.com/andruhovski/apdf-tools/issues
Project-URL: Repository, https://github.com/andruhovski/apdf-tools
Description-Content-Type: text/markdown

# 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:

```powershell
python -m pip install apdf-cloud-cli
```

Check that the CLI is available:

```powershell
apdf-cloud-cli --help
apdf --help
```

For local development from a checkout:

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

## Configuration

Set credentials before running CLI commands or the MCP server:

```powershell
$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`](.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.

```powershell
apdf-cloud-cli storage list /
apdf-cloud-cli storage upload .\sample.pdf /sample.pdf
apdf-cloud-cli storage download /sample.pdf .\sample.pdf
apdf-cloud-cli pdf merge /a.pdf /b.pdf merged.pdf
apdf-cloud-cli pdf extract-text sample.pdf --output sample.txt
apdf-cloud-cli mcp serve
```

## MCP Usage

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

```powershell
apdf-cloud-cli mcp serve
```

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

## Codex Prompts

Sample prompts for using this MCP server with Codex are in
[docs/codex-prompts.md](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:

```powershell
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:

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

Use `--force` to replace an existing installed copy. More details are in
[docs/agent-skill.md](docs/agent-skill.md).

## Development

Run the default unit test suite:

```powershell
python -m pytest -q
```

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

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

More live-test setup notes are in [docs/live-tests.md](docs/live-tests.md).

Build and validate the package distributions:

```powershell
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](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:

```powershell
git tag v0.2.0
git push origin v0.2.0
```

## Stage 2 Roadmap

- Split PDF files
- Extract images from PDF files
- Extract tables from PDF files

