System Requirements
| Requirement | Details |
|---|---|
| Python | 3.12 or 3.13 |
| Operating System | macOS, Linux, or Windows |
| Internet connection | Required: used for authentication and LLM provider API calls. Your SQL source code is never sent to the 3XDE backend; only auth/licensing metadata and calls to your LLM provider go over the network. |
| Account | A 3XCode account (Free tier included, 5 conversions/month), created via `3xcode login --signup` |
Install the CLI
3XCode CLI is published on PyPI as 3xcode-cli. Install it with pip or uv.
pip install 3xcode-cli # or, with uv (preferred if you use uv) uv add 3xcode-cli # verify the install 3xcode version
3xcode version prints the installed CLI version, your Python version, and your platform/architecture, a quick sanity check that the command is on your PATH.
Log In (or Create an Account)
If you don't have an account yet, create one with --signup. Existing users can just run 3xcode login.
# Create a new account 3xcode login --signup --email you@example.com --password "your-password" --name "Your Name" # Already have an account? Log in directly... 3xcode login --email you@example.com --password "your-password" # ...or just run "3xcode login" with no flags for a browser-based # device-flow login (handy for headless machines / CI) 3xcode login
Convert Your First File
Conversions run inside a workspace (a folder 3XCode uses to organize input, output, and session state). Initialize one, then convert a SQL file with 3xcode pyspark convert.
# One-time setup: initialize a workspace in an empty directory 3xcode workspace init ./my-migration --name my-migration cd my-migration # Convert a single SQL file to PySpark 3xcode pyspark convert your_file.sql
This runs the full 5-phase pipeline (discovery, planning, conversion, validation, and auto-fix) against your_file.sql. Add -v / --verbose to see streaming output and tool calls as it runs, or --model opus|sonnet|haiku to override your account's default model for this run.
Where the Output Goes
Every conversion writes into your workspace's output/ directory, under a folder named after your session. For your_file.sql you'll get:
| Path | Contents |
|---|---|
output/<session>/your_file/pyspark/*.py | The converted PySpark module(s), split by dependency group (utilities, standalone jobs, main pipeline) |
output/<session>/your_file/reports/*.json | Raw phase artifacts: discovery inventory, conversion plan |
output/<session>/your_file.py | The main-pipeline file, also copied to the top level for convenience |
output/<session>/your_file_audit.md | Human-readable audit: confidence/completion grade (A+–F), issues found, TODOs |
output/<session>/your_file_audit.json | The same audit as structured JSON |
Check 3xcode session status <id> or 3xcode session info <id> any time to see per-file status, cost, and success rate for a session.
Try Bulk Conversion & the Interactive Shell
Once single-file conversion feels good, point 3XCode at an entire directory. It converts every .sql file in parallel, and the run can be resumed if interrupted.
# Convert every .sql file in ./sql/, named and tracked as a session 3xcode pyspark convert --dir ./sql/ --session "my-migration" -w 4 # --session sets a human-friendly label, not the resumable ID. # List sessions to get the real ID (looks like session-<date>-my-migration): 3xcode session list # Watch progress live, using the ID from the list above 3xcode session status <session-id> --watch # Resume an interrupted bulk run, same ID 3xcode pyspark convert --resume <session-id>
Bulk Conversion
-w / --workers sets parallel worker count (0 = auto-detect based on your CPU/RAM). --schedule simple-first|complex-first controls the order files are processed in.
Interactive Shell
Run bare `3xcode` with no subcommand to launch the interactive REPL shell: tab completion, syntax highlighting, and the same commands without retyping `3xcode` each time.
Prefer a browser? 3xcode ui launches a local web UI (default http://localhost:3210) with the same workspace, session, and bulk-conversion features in a point-and-click interface.