CLI Reference¶
Complete reference for the pylocket command-line tool.
Global Options¶
These options apply to all commands:
| Option | Description | Default |
|---|---|---|
--api-url <URL> |
Override the PyLocket API base URL | https://api.pylocket.com |
--token <TOKEN> |
Override the authentication token | Read from ~/.pylocket/credentials |
--help, -h |
Show help for any command | — |
--version |
Show the CLI version | — |
The PYLOCKET_TOKEN environment variable can also be used instead of --token.
pylocket login¶
Authenticate with the PyLocket API.
Options¶
| Option | Description |
|---|---|
--email <EMAIL> |
Account email (prompted interactively if omitted) |
--password <PASSWORD> |
Account password (prompted interactively if omitted) |
--token <TOKEN> |
Authenticate directly with an API token (skips interactive login) |
Behavior¶
- On success, stores credentials at
~/.pylocket/credentials - If 2FA is enabled, prompts for a TOTP code after password
- The stored token is reused for subsequent commands until it expires
Examples¶
# Interactive login
pylocket login
# Non-interactive login (for scripts)
pylocket login --email dev@example.com --password "s3cret"
# Token-based login (for CI/CD)
pylocket login --token "eyJhbGc..."
pylocket apps¶
Manage registered applications.
pylocket apps create¶
Register a new application.
| Option | Description | Required |
|---|---|---|
--name <NAME> |
Application display name | Yes |
--platform <PLATFORM> |
Target platform(s). Repeatable. | Yes (at least one) |
Valid platform values: win-x64, linux-x64, linux-arm64, mac-x64, mac-arm64
pylocket apps list¶
List all registered applications.
| Option | Description |
|---|---|
--format <FORMAT> |
Output format: table (default), json |
pylocket apps update¶
Update an existing application.
| Option | Description |
|---|---|
--app <APP_ID> |
Application ID (required) |
--name <NAME> |
New display name |
--platform <PLATFORM> |
Replace platform list. Repeatable. |
--offline-grace-hours <HOURS> |
Offline grace period in hours |
pylocket apps delete¶
Delete a registered application.
Warning: Deleting an app revokes all associated licenses and removes all builds. This action cannot be undone.
pylocket protect¶
Upload and protect an application artifact.
pylocket protect --app <APP_ID> --artifact <PATH> --platform <PLATFORM> --python <VERSION> [OPTIONS]
Options¶
| Option | Description | Required | Default |
|---|---|---|---|
--app <APP_ID> |
Application ID | Yes | — |
--artifact <PATH> |
Path to the artifact to protect | Yes | — |
--platform <PLATFORM> |
Target platform | Yes | — |
--python <VERSION> |
Python version used to build the artifact | Yes | — |
--out <DIR> |
Auto-download to this directory when ready | No | — |
Valid Python versions: 3.9, 3.10, 3.11, 3.12, 3.13
Supported Artifact Types¶
| Extension | Description |
|---|---|
.py, .pyz, .pyw |
Python scripts |
.whl, .egg |
Python packages |
.zip |
ZIP archives |
.tar.gz, .tgz, .tar.bz2 |
Compressed tar archives |
.exe |
Windows executables (PyInstaller, cx_Freeze, etc.) |
| (no ext) | Linux/macOS executables |
.app |
macOS application bundles (zipped) |
Examples¶
# Protect an application
pylocket protect \
--app app_abc123 \
--artifact dist/myapp.exe \
--platform win-x64 \
--python 3.12
# Protect and auto-download
pylocket protect \
--app app_abc123 \
--artifact dist/myapp.exe \
--platform win-x64 \
--python 3.12 \
--out dist/protected/
pylocket status¶
Check the status of a protection build.
Options¶
| Option | Description |
|---|---|
--build <BUILD_ID> |
Build ID to check |
--app <APP_ID> |
App ID (used with --latest) |
--latest |
Show the most recent build for the app |
--format <FORMAT> |
Output format: table (default), json |
Build Statuses¶
| Status | Description |
|---|---|
QUEUED |
Job is in the protection queue |
PROCESSING |
Bytecode extraction and encryption in progress |
SCANNING |
Malware scan running |
PACKAGING |
Re-packaging the protected artifact |
READY |
Protection complete — ready for download |
FAILED |
An error occurred |
Examples¶
# Check a specific build
pylocket status --build build_abc789
# Check the latest build for an app (JSON output)
pylocket status --app app_abc123 --latest --format json
pylocket fetch¶
Download a protected artifact.
Options¶
| Option | Description | Required |
|---|---|---|
--build <BUILD_ID> |
Build ID to download | Yes |
--out <DIR> |
Output directory | Yes |
Example¶
The command creates the output directory if it does not exist.
pylocket licenses¶
Manage end-user licenses.
pylocket licenses create¶
Create a new license key.
| Option | Description | Default |
|---|---|---|
--app <APP_ID> |
Application ID | (required) |
--email <EMAIL> |
End-user email | (optional) |
--device-limit <N> |
Max devices | 2 |
--expires <DATE> |
Expiration date (YYYY-MM-DD) | None (no expiry) |
--type <TYPE> |
License type: standard, demo |
standard |
pylocket licenses list¶
List licenses for an application.
| Option | Description |
|---|---|
--app <APP_ID> |
Application ID |
--status <STATUS> |
Filter by status: active, revoked, expired, demo |
--format <FORMAT> |
Output format: table, json |
pylocket licenses get¶
Get details for a specific license.
pylocket licenses revoke¶
Revoke a license.
pylocket licenses reset-devices¶
Clear all device activations for a license.
pylocket licenses extend¶
Extend a license expiration date.
pylocket auth¶
Manage authentication and security settings.
pylocket auth api-keys rotate¶
Generate a new API key and invalidate the old one.
pylocket auth 2fa setup¶
Start 2FA setup. Returns a QR code URI for your authenticator app.
pylocket auth 2fa confirm¶
Confirm 2FA setup with a TOTP code.
pylocket auth 2fa status¶
Check 2FA status and remaining backup codes.
pylocket auth 2fa disable¶
Disable 2FA.
Environment Variables¶
| Variable | Description | Equivalent Option |
|---|---|---|
PYLOCKET_TOKEN |
Authentication token | --token |
PYLOCKET_API_URL |
API base URL | --api-url |
Exit Codes¶
| Code | Meaning |
|---|---|
0 |
Success |
1 |
General error |
2 |
Authentication error |
3 |
Network error (API unreachable) |
4 |
Validation error (invalid arguments) |
5 |
Build failed |
Credential Storage¶
Credentials are stored at ~/.pylocket/credentials in JSON format. The file contains:
- Access token (JWT, expires after the configured TTL)
- Refresh token
- API URL
The file permissions are set to 600 (owner read/write only).
To clear stored credentials: