CLI Reference¶

PHALUS is CLI-first. Every capability is accessible from the command line; the web UI is a convenience wrapper over the same pipeline.

phalus [COMMAND] [OPTIONS]

Run phalus --help for a summary or phalus [COMMAND] --help for per-command help.

Commands¶

plan¶

Parse a manifest file and display the packages that would be processed. No network calls to registries or LLMs are made. Use this to preview filtering before a long run.

phalus plan <MANIFEST> [OPTIONS]

Arguments¶

Options¶

Example¶

phalus plan package.json

phalus plan package.json --only lodash,chalk

phalus plan requirements.txt --exclude boto3,botocore

Output:

Manifest: package.json (5 packages, 3 after filtering)

PACKAGE                        VERSION          ECOSYSTEM
-------------------------------------------------------
lodash                         ^4.17.21         npm
express                        ^4.18.2          npm
chalk                          ^5.3.0           npm

run¶

Run the full clean room pipeline for all packages in a manifest. Packages are processed concurrently up to the configured limit.

phalus run <MANIFEST> [OPTIONS]

Arguments¶

Options¶

Exit codes¶

Examples¶

# Basic run, MIT license
phalus run package.json

# Apache-2.0 output into a specific directory
phalus run package.json --license apache-2.0 --output ./liberated/

# Process only two packages
phalus run package.json --only lodash,express

# Reimplement JavaScript packages in Rust
phalus run package.json --target-lang rust --license apache-2.0

# Dry run: trigger Agent A only, produce CSP specs without code generation
phalus run package.json --dry-run

# Dry run a single package, then build from the CSP later
phalus run-one npm/[email protected] --dry-run
phalus build ./phalus-output/lodash/.cleanroom/csp/

# Stricter similarity threshold
phalus run package.json --similarity-threshold 0.50

# Stronger isolation mode
phalus run package.json --isolation process

run-one¶

Run the clean room pipeline on a single package without needing a manifest file. Useful for quick experiments and testing a specific package.

phalus run-one <PACKAGE> [OPTIONS]

Arguments¶

Supported ecosystems: npm, pypi, crates, go.

Options¶

Examples¶

phalus run-one npm/[email protected]

phalus run-one npm/[email protected] --license apache-2.0

phalus run-one pypi/[email protected] --output ./py-output/

phalus run-one npm/[email protected] --target-lang rust --license mit

phalus run-one crates/[email protected] --isolation process

build¶

Run Agent B (Builder) from an existing Clean Room Specification Pack without re-running Agent A. This is the second half of the split pipeline workflow:

1. Generate a CSP with --dry-run (Agent A only)
2. Optionally review or modify the CSP files on disk
3. Run build to implement from the CSP (Agent B only)

phalus build <CSP> [OPTIONS]

Arguments¶

Options¶

Examples¶

# Build from a CSP directory (looks for manifest.json inside)
phalus build ./phalus-output/lodash/.cleanroom/csp/

# Build from a specific manifest.json
phalus build ./my-specs/lodash-csp/manifest.json --license apache-2.0

# Build in a different language
phalus build ./phalus-output/chalk/.cleanroom/csp/ --target-lang rust

# Full split workflow: generate CSP, review it, then build
phalus run-one npm/[email protected] --dry-run
# ... inspect and optionally edit the CSP files ...
phalus build ./phalus-output/express/.cleanroom/csp/ --license mit

Split pipeline workflow¶

The build command enables a split pipeline where Agent A and Agent B run as separate steps. This is useful for:

• Reviewing the CSP before committing to implementation
• Injecting custom constraints into the specification (e.g. security requirements in 03-behavior-spec.json or 04-edge-cases.json)
• Reusing a CSP to generate implementations in multiple languages
• Iterating on the implementation without re-running analysis

See the Cookbook for detailed examples of these workflows.

scan¶

Scan a project directory, manifest file, or SBOM file for dependency licenses. Identifies all dependencies, resolves their license metadata from package registries, normalizes license strings to SPDX identifiers, and classifies them into risk buckets.

Supports reading manifests (package.json, requirements.txt, Cargo.toml, go.mod) and SBOM files (CycloneDX JSON 1.4+, SPDX JSON 2.3+).

phalus scan <PATH> [OPTIONS]

Arguments¶

Options¶

Exit codes¶

License classification¶

Each dependency license is normalized to an SPDX identifier and classified:

Supported SBOM formats¶

Examples¶

# Scan a project directory (finds all manifests and SBOMs recursively)
phalus scan ./my-project

# Scan a single manifest
phalus scan package.json

# Scan a CycloneDX SBOM
phalus scan bom.json

# Offline scan (no registry calls)
phalus scan ./my-project --offline

# JSON output, saved for later retrieval via the API
phalus scan ./my-project --output json --save

# High concurrency for large projects
phalus scan ./monorepo --concurrency 16

Sample text output:

Scan: ./my-project (42 packages from 1 manifest, 0 SBOMs)

PACKAGE                VERSION     ECOSYSTEM  LICENSE         CLASS
---------------------------------------------------------------------------
lodash                 4.17.21     npm        MIT             permissive
express                4.18.2      npm        MIT             permissive
pg                     8.11.3      npm        MIT             permissive
react                  18.2.0      npm        MIT             permissive
node-forge             1.3.1       npm        BSD-3-Clause    permissive
sharp                  0.33.2      npm        Apache-2.0      permissive
readline-sync          1.4.10      npm        MIT             permissive

Summary: 40 permissive, 1 copyleft-weak, 0 copyleft-strong, 1 unknown

Stored scans¶

When --save is used, the scan result is persisted to ~/.phalus/scans/{uuid}.json. Stored scans can be listed and retrieved through the REST API.

inspect¶

Display the contents of a completed job's output directory. With no flags, all sections are shown. Use individual flags to show only what you need.

phalus inspect <OUTPUT_DIR> [OPTIONS]

Arguments¶

Options¶

If none of --audit, --similarity, or --csp are given, all three sections are shown.

Example¶

# Show everything
phalus inspect ./phalus-output

# Show only similarity scores
phalus inspect ./phalus-output --similarity

# Show only the CSP inventory
phalus inspect ./phalus-output --csp

# Show only the audit log
phalus inspect ./phalus-output --audit

Sample similarity output:

=== Similarity Reports ===
  [email protected]:
    token_similarity: 0.1200
    name_overlap:     0.8900
    string_overlap:   0.1500
    overall_score:    0.2800
    verdict:          PASS

validate¶

Re-run the validation stage on an existing output directory without regenerating any code. Useful for checking outputs against a different similarity threshold, or after manually reviewing generated files.

phalus validate <OUTPUT_DIR> [OPTIONS]

Arguments¶

Options¶

Exit codes¶

Example¶

phalus validate ./phalus-output

phalus validate ./phalus-output --similarity-threshold 0.50

Sample output:

PASS lodash (similarity: 0.2800, license: ok)
PASS chalk (similarity: 0.1900, license: ok)
FAIL express (similarity: 0.7200, license: ok)

config¶

Print the active configuration, merging ~/.phalus/config.toml with any PHALUS_* environment variable overrides. API keys are always redacted (shown as ***).

phalus config

No options or arguments.

Example¶

phalus config

Sample output:

[llm]
agent_a_provider = "anthropic"
agent_a_model = "claude-sonnet-4-6"
agent_a_api_key = "***"
agent_a_base_url = ""
agent_b_provider = "anthropic"
agent_b_model = "claude-sonnet-4-6"
agent_b_api_key = "***"
agent_b_base_url = ""

[isolation]
mode = "context"

[limits]
max_packages_per_job = 50
max_package_size_mb = 10
concurrency = 3
...

serve¶

Start the local web UI. The server binds to 127.0.0.1:3000 by default and is accessible only from the local machine.

phalus serve [OPTIONS]

Options¶

Example¶

# Default: localhost only
phalus serve

# Custom port
phalus serve --port 8080

# Bind to all interfaces (use with caution — no authentication)
phalus serve --host 0.0.0.0 --port 3000

After starting, open http://127.0.0.1:3000 in a browser.

See Web UI for a description of the interface and API Reference for the backing REST endpoints.