This is the fastest path to seeing 3XCode CLI convert real code: authenticate once, initialize a workspace, then hand it a single .sql file. The CLI runs it through the full five-phase pipeline (discovery, planning, conversion, validation, and auto-fix) and writes back a production-ready PySpark module plus a full audit report you can hand to a reviewer. Every command below is real and copy-pasteable.

Prerequisites

Step 1: Log In

Authenticate before anything else: every pipeline phase requires a valid login and license. Running 3xcode login with no flags opens the device-flow login in your browser, which is the easiest option on a developer machine.

3xcode login
# Opens your browser to a verification URL and shows a short code to enter.
# Waiting for you to approve in the browser (expires in 10 min)...
# ✓ Logged in as you@company.com

Prefer not to use a browser? Log in directly with email and password instead:

3xcode login --email you@company.com --password yourpassword

# Or omit --password to be prompted securely:
3xcode login --email you@company.com

Confirm you're in with 3xcode status, which shows your plan tier, license validity, and conversions remaining this month.

Step 2: Set Up a Workspace

Conversions run inside a workspace, a local project folder that organizes input SQL, converted output, and session history.pyspark convertrequires an active workspace before it will run.

3xcode workspace init ./my-migration --name "my-migration"
# Creates input/, output/, .sessions/, logs/ and sets this workspace active.

cd ./my-migration
3xcode workspace status

Drop your SQL file anywhere you like inside (or outside) the workspace. You'll point the CLI at it directly by path in the next step. If you already have a workspace set up, just make sure it's active with 3xcode workspace set ./my-migration.

Step 3: Analyze the File (Optional)

Before committing a full conversion, you can run just the Discovery and Planning phases withpyspark analyze. This detects the source SQL dialect and platform, inventories every convertible object (procedures, functions, views), and estimates complexity, without generating any PySpark code yet. It still authenticates and calls an LLM, so it isn't free of API usage, but it's a useful sanity check on a file you haven't seen before.

3xcode pyspark analyze your_file.sql

# Output written under the workspace output directory:
# output/your_file/reports/discovery.json: detected dialect, platform, and object inventory

Step 4: Convert the File

Run the conversion. For a single file, this is as simple as pointingpyspark convert at the path:

3xcode pyspark convert your_file.sql

This kicks off all five phases in order (Discovery, Planning, Conversion, Validation, and Auto-Fix) and creates a mini-session under output/<session_id>/. A few useful variations:

# Stream tool calls and intermediate output as it runs
3xcode pyspark convert your_file.sql --verbose

# Pick a specific model instead of your account default
3xcode pyspark convert your_file.sql --model sonnet

# Skip the auto-fix phase (Phase 5) if you only want raw + validated output
3xcode pyspark convert your_file.sql --skip-audit

# Run in the background and get your terminal back immediately
3xcode pyspark convert your_file.sql --detach

No arguments at all? Running bare 3xcode pyspark convert opens an interactive file picker so you can browse to the file instead of typing the path.

Step 5: Monitor Progress

In the foreground, progress prints live to your terminal as each phase completes. If you ran with --detach, or want to check on a conversion from another terminal, look it up by session and watch it live:

# Find the session ID
3xcode session list

# Watch it live: tails phase transitions and file-level events
3xcode session status session-20260712-your-file --watch

The status view shows worker phase, current file, and per-phase durations, plus an ETA once enough of the run has completed to estimate against. Session state moves throughcreated →in_progress →completed (orpartially_completed if some objects failed).

Step 6: Review the Output

Once the session reaches completed, the workspace's output directory contains everything the pipeline produced for that file:

output/your_file/
├── pyspark/                  # One generated .py module per output group
│   ├── utilities.py
│   └── main_pipeline.py
├── reports/
│   ├── discovery.json        # Detected dialect, platform, object inventory
│   └── conversion_plan.json  # Dependency graph + per-object instructions
output/your_file.py            # Copy of the main pipeline module (CLI-friendly path)
output/your_file_audit.md      # Human-readable audit report
output/your_file_audit.json    # Canonical full audit report

Open the generated .py file(s) directly: each one carries a header comment naming the detected source platform, its confidence, and the exact markers that identified it, so you always know what the pipeline thought it was converting from.

Step 7: Review the Audit Report

your_file_audit.md is the single most important file to read before shipping the conversion. It sorts every validation finding into one of four developer action buckets, each with a priority and (where applicable) a prescriptive fix:

At the top of the report, each output file gets a completion percentage (did the pipeline finish and produce valid, dependency-resolved PySpark?) and aconfidence percentage (how sure the validation pass is that it's actually correct), and the lower of the two becomes the file's letter grade, A+ through F. Read the audit for any file that isn't graded near the top of the scale before you trust it in production.

Success Criteria

Use this checklist to confirm a single-file conversion is genuinely done, not just finished:

Troubleshooting