Contents
1. Create a Publisher Account
Register via web or CLI
Go to /register to create your account through the browser, or run:
ppm registerYou will receive an API key. Save it — it is shown only once.
Authenticate the CLI
ppm loginPaste your API key when prompted. It is stored in ~/.ppm/config.
2. Package Structure
A PPM package is a .paipkg file — a ZIP archive with:
mypackage/
pai.package <- manifest (required)
mypackage.pai <- source file(s)
README.md <- optional but recommendedThe archive must contain pai.package at the root level.
3. Writing pai.package
The manifest is an INI-format file:
[package]
name = my-package
version = 1.0.0
author = yourusername
type = pai
category = utilities
description = Short one-line description of what this package does.
[dependencies]
; list other packages this one requires
json-parser = 1.0.0| Field | Required | Description |
|---|---|---|
name | Yes | Lowercase, hyphens allowed. Must be unique in the registry. |
version | Yes | Semantic version: MAJOR.MINOR.PATCH |
author | Yes | Your registered username. |
type | Yes | pai or clib (see below) |
category | Yes | One of the categories listed on the package index. |
description | Yes | One sentence, max 200 characters. |
[dependencies] | No | name = version pairs of required packages. |
4. Package Types
PAI packages
Written in PascalAI and distributed as source code. These are the most common type. All standard functionality, AI features, and pure-Pascal algorithms belong here.
CLib packages
Wrap a native C library (e.g. libpq, zlib, sqlite3). They include platform-specific
compiled artifacts or FFI bindings. Use type = clib only when a native
library integration is required.
When in doubt, use type = pai. CLib packages require more packaging
effort and limit portability.
5. Publishing a Package
Initialize a new package
mkdir my-package
cd my-package
ppm initThis creates a starter pai.package manifest in the current directory.
Add your source files
Place your .pai source files in the directory. The main file should
share the name of your package.
Publish
ppm publish --dir ./my-packagePPM will zip the directory, validate the manifest, and upload to the registry. On success it prints the package URL.
The maximum package size is 50 MB. Do not include build artifacts, compiled binaries, or large data files in the package.
6. Updating a Package
Bump the version field in pai.package and run
ppm publish again. Versions must increase monotonically —
you cannot re-publish an existing version.
; pai.package — bump from 1.0.0 to 1.1.0
version = 1.1.0ppm publish --dir ./my-package7. Publishing Guidelines
- Names: Use lowercase, hyphens only. Avoid generic names like
utilsorlib. - Descriptions: Be specific. "HTTP client with REST support" is better than "HTTP utilities".
- Versions: Follow Semantic Versioning. Breaking changes require a major version bump.
- Dependencies: Declare all dependencies in
[dependencies]. Do not bundle copies of other PPM packages. - License: Include a
LICENSEfile. MIT, Apache 2.0, and MPL 2.0 are recommended. - No malware: Packages that perform destructive, deceptive, or unauthorized operations will be removed and the account banned.
- No name squatting: Register packages you intend to maintain. Inactive packages may be reclaimed.
Open an issue at github.com/pascalai/ppm or email registry@pascalai.org.