CLI Reference
Every magiclock subcommand and flag in one place.
Everything is one command: magiclock <subcommand> [options]. magiclock --version prints the installed version; bare magiclock prints help.
activate
Authenticate and provision this machine. Idempotent — safe to run again.
| Flag | Meaning |
|---|---|
--server URL | License server URL (falls back to a saved session, then $MAGICLOCK_SERVER). |
--token TOKEN | Bearer token (falls back to a saved session, then $MAGICLOCK_TOKEN). |
--with-token | Headless mode: read a portal-minted token from $MAGICLOCK_TOKEN or stdin. |
--no-browser | If sign-in is needed, print a link + code instead of opening a browser. |
status
Show this machine's account and activation state.
| Flag | Meaning |
|---|---|
--offline | Skip the live server round-trip; report from local state only. |
protect
Encrypt a .py file (or a directory, recursively) into a gated .pya.
magiclock protect PATH [-o OUT] [--remove]
[--trial | --expires-in DURATION | --expires-at DATE]
[--lock-passphrase | --no-bind-machine [--passphrase | --emit-key]]| Flag | Meaning |
|---|---|
PATH | A .py file or a directory to protect recursively (.venv, venv, __pycache__, .git, dist, build are skipped automatically). |
-o, --out | Output path (or output root, for directories). |
--remove | Delete the plaintext .py file(s) after encrypting. |
--trial | Fixed 48-hour self-destruct — for demos. |
--expires-in DURATION | Stops decrypting after a duration (e.g. 30d). |
--expires-at DATE | Stops decrypting on a date (e.g. 2026-12-31). |
--lock-passphrase | Two-factor lock: this machine and a passphrase. |
--no-bind-machine | Portable artifact — no machine lock. |
--passphrase | With --no-bind-machine: unlock with a passphrase ($MAGICLOCK_PASSPHRASE or a prompt). |
--emit-key | With --no-bind-machine: print a generated key for out-of-band distribution instead of a passphrase. |
--trial/--expires-in/--expires-at are mutually exclusive with each other; --lock-passphrase is mutually exclusive with the --no-bind-machine group.
protect-model
Encrypt a model or any other resource into a .enc envelope. Takes the same expiry, --lock-passphrase, and portable flags as protect, plus:
| Flag | Default | Meaning |
|---|---|---|
PATH | — | The file to encrypt. |
-o, --out | <path>.enc | Output path. |
--feature NAME | ai_model | The license capability required to unlock this artifact. |
--remove | off | Delete the plaintext file after encrypting. |
build
Compile an app to a native binary, inserting the license gate into every module automatically. See Compiled Build for the full walkthrough.
| Flag | Default | Meaning |
|---|---|---|
entry | — | Entry-point .py file. |
-o, --output-dir | dist | Build output directory. |
--source-root | the entry file | Project root to scan/transform. |
--module | on | Compile to a single-file native extension. |
--standalone | — | Compile to a self-contained app directory instead. Mutually exclusive with --module. |
--no-compile | off | Scan + inject + embed only, skip the native compile. |
--keep-tmp | off | Keep the intermediate transform directory. |
--model PATH | none | Encrypt and bundle a model (repeatable). |
--model-lock-passphrase | off | Two-factor lock for bundled models (needs ≥1 --model). |
--model-trial / --model-expires-in / --model-expires-at | none | Expiry for bundled models — mutually exclusive with each other. |
run
Run a .py or .pya, gate included.
| Flag | Default | Meaning |
|---|---|---|
entry | — | The file to run. |
--app-version | 1.0.0 | App version, checked against any max_app_version your license sets. |
--passphrase | off | Prompt for a decryption passphrase (or read $MAGICLOCK_PASSPHRASE) — for portable or two-factor artifacts. |
--key KEY | — | Portable artifact decryption key (base64), or read $MAGICLOCK_DECRYPT_KEY. |
deactivate
Remove this machine from your account.
| Flag | Meaning |
|---|---|
--local-only | Clear the local vault without releasing the seat or revoking on the server. |
--server URL | Server URL for the release call. |
--token TOKEN | Bearer token for the release call. |
completion
Print a shell tab-completion script.
magiclock completion bash > /etc/bash_completion.d/magiclock
magiclock completion zsh > "${fpath[1]}/_magiclock"