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.

shell

magiclock protect PATH [-o OUT] [--remove]
                  [--trial | --expires-in DURATION | --expires-at DATE]
                  [--bind-machine [--passphrase] | --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`).
(no binding flag)	Default: keyless portable — decrypts on any machine with `magiclock` installed; no lock, no secret.
`--bind-machine`	Machine-locked artifact: decrypts only on this activated machine. Add `--passphrase` for a two-factor lock (machine and passphrase).
`--passphrase`	Unlock with a passphrase (`$MAGICLOCK_PASSPHRASE` or a prompt) — portable on its own, second factor with `--bind-machine`.
`--emit-key`	Portable artifact unlocked by a generated key, printed for out-of-band distribution.

--trial/--expires-in/--expires-at are mutually exclusive with each other; --passphrase and --emit-key are mutually exclusive; --emit-key cannot be combined with --bind-machine.

protect-model

Encrypt a model or any other resource into a .enc envelope. Takes the same expiry and binding flags as protect (keyless portable by default, --passphrase/--emit-key, --bind-machine [+ --passphrase]), 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` and `--bind-machine`).
`--model-trial` / `--model-expires-in` / `--model-expires-at`	none	Expiry for bundled models — mutually exclusive with each other.
`--bind-machine`	off	Machine-locked build: license gate compiled into every module; runs only under this machine's vault. Default (without it) is a portable build — no gate, runs anywhere, keyless models.
`--passphrase` / `--emit-key`	off	Portable builds only: bundled models use a passphrase-derived or generated shared key instead of the keyless default.

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.

skill

Install a Claude Code skill into this project so an AI coding agent (like Claude Code) knows how to protect it with MagicLock.

shell

magiclock skill [--dir DIR] [--force] [--print]

Flag	Meaning
`--dir DIR`	Project root to install into (default: the current directory).
`--force`	Overwrite an existing `SKILL.md`.
`--print`	Print the skill content to stdout instead of writing a file.

Writes .claude/skills/magiclock-protect/SKILL.md, which teaches the agent to pick a protection tier and drive protect/build correctly for your project.

completion

Print a shell tab-completion script.

shell

magiclock completion bash > /etc/bash_completion.d/magiclock
magiclock completion zsh  > "${fpath[1]}/_magiclock"

PreviousAccount & Activation NextPython API Reference