General
What is 3XCode CLI?
3XCode CLI is an AI-powered command-line tool that migrates SQL codebases (T-SQL, PL/SQL, PL/pgSQL, MySQL, Spark SQL, and generic ANSI SQL) to production-ready PySpark. Install it with pip install 3xcode-cli (or uv add 3xcode-cli) and run the SQL-to-PySpark agent with 3xcode pyspark convert. It runs a 5-phase pipeline (Discovery, Planning, Conversion, Validation, and Auto-Fix) that detects your source SQL dialect and platform, produces idiomatic PySpark code, validates it against your other converted files, and applies safe, targeted fixes to anything that needs correction.
How is 3XCode different from manual migration?
| Aspect | Manual Migration | 3XCode CLI |
|---|---|---|
| Speed | Manual, script-by-script effort | Automated single run, parallel batches for bulk jobs |
| Cross-file consistency | Easy to miss dependent signatures | Dependency-ordered conversion (views → functions → procedures → triggers) |
| Platform-specific gotchas | Relies on institutional knowledge | Built-in gotcha knowledge base (date functions, NULL semantics, window frames, API deprecations) |
| Validation | Manual code review only | Automated syntax + cross-file dependency validation, plus targeted auto-fix |
| Resumability | Start over if interrupted | Batches and sessions resume with `3xcode batch resume` / `3xcode session resume` |
Billing & Quota
What am I billed for?
Only conversions that complete successfully. A file that fails, times out, or is never attempted because a run was cancelled or interrupted doesn't count against your monthly allowance. Starting a batch holds quota covering its files up front, and any part of that hold left unused when the batch finishes, pauses, or is cancelled is released back to your account immediately. See Billing & Quota for the full breakdown.
Your plan determines your monthly conversion allowance and how many machines can be licensed to your account at once.
| Tier | Conversions / Month | Machines per License |
|---|---|---|
| Free | 5 | 1 |
| Pro | 200 | 2 |
| Team | 1,000 | 10 |
| Enterprise | Unlimited | 999 |
Run 3xcode status at any time to see your current plan, conversions used this month, and remaining allowance. Organization-shared licenses (via 3xcode org create / 3xcode org join) are exempt from the per-machine cap since they're shared by design, and resolve org-first with your individual license as a fallback.
Batches & Updates
What happens if a batch fails midway?
Files that already completed stay completed. A file that was actually in progress when the failure happened is marked so it can be retried; files that never got a chance to run are simply pending. Run 3xcode batch resume <session_id> <batch_id> (or 3xcode session resume <id> for the older single-run flow) and only the unfinished files are re-attempted, under the same success-only billing: a file is only charged once, for the attempt that actually succeeds.
How do updates work?
3xcode never updates itself silently. It checks PyPI in the background and, if a newer version exists, prints a short notice on your next command. Run 3xcode update to upgrade (it detects whether you used pip, pipx, or uv and runs the right command), or 3xcode update --check to see the latest version without installing anything. Set THREEXCODE_DISABLE_UPDATE_CHECK to silence the notice entirely. See Installation & Updates.
Can I schedule a conversion to run later?
Yes, two ways: 3xcode batch schedule --at/--in for a quick, one-off delay that runs as a background process on your machine, or 3xcode schedule add for a durable, repeatable schedule that survives a reboot. See Scheduled Conversions.
Security & Privacy
Does my SQL code get sent to your servers?
No. Your source SQL code is never sent to the 3XDE backend. The CLI runs on your machine and talks directly to your configured AI provider (Anthropic, AWS Bedrock, Google Vertex AI, or Azure AI Foundry) for the actual conversion work. Your code goes straight from your machine to the provider you've chosen, and nowhere else. The 3XDE backend only ever handles auth, licensing, provider-key metadata, and usage tracking; it never sees the SQL you're converting or the PySpark it produces.
Sent to your provider, not to us
Conversion happens directly against your AI provider. The backend's role is limited to auth, licensing, and usage tracking, not code processing.
Local Credential Storage
Login credentials and BYOK provider keys are stored locally via your OS keychain (or a permission-locked local file as fallback), never on our servers.
Machine Binding, Not Tracking
A one-way hashed machine fingerprint (hostname + architecture + OS, deliberately not MAC address, which is unstable across processes on some OSes) is sent on authenticated requests solely to enforce your tier's device cap. Raw system details are never transmitted.
Prompts Fetched, Not Shipped
Conversion prompts and the knowledge base are served by the backend at runtime rather than shipped in the package, protecting the proprietary logic without exposing your code to build it.
Supported Dialects
Which SQL dialects can I convert?
Discovery automatically detects one of the following source dialects for every file you convert, with no configuration needed:
- tsql: SQL Server / T-SQL (also covers Azure SQL, Synapse)
- plsql: Oracle PL/SQL
- plpgsql: PostgreSQL PL/pgSQL (also covers Redshift)
- mysql: MySQL
- ansi: Generic ANSI SQL, covering Snowflake, BigQuery, and Teradata syntax not covered by a more specific dialect
- spark_sql: Spark SQL / Databricks SQL / Hive; since this shares the target engine, conversion here is about idiom and readability rather than correctness
- unknown: Unrecognized syntax is still attempted rather than rejected
Alongside dialect detection, a separate deterministic layer fingerprints the specific source platform (Databricks, Snowflake, PostgreSQL, MySQL, SQL Server, Oracle, Redshift, BigQuery, Teradata, or Hive) using regex markers. No LLM call is required, and the matched markers are fully explainable.
Can I request support for more dialects?
Yes. Use 3xcode contact-admin -m "..." to send a message to your admin with your request.
BYOK (Bring Your Own Key)
Do I need my own API key?
No. By default, 3XCode uses a platform-provided key, so you can start converting right after 3xcode login with no key setup. BYOK is optional: it lets you route conversions directly to your own provider account instead. BYOK must first be enabled for your account by an admin: request it with 3xcode contact-admin -m "Please enable BYOK for my account", then configure a provider with 3xcode keys store --provider <provider>.
Which providers are supported?
| Provider | Value | Notes |
|---|---|---|
| Anthropic | anthropic | Direct API access; the default provider |
| AWS Bedrock | bedrock | Access key, secret key, and AWS region |
| Google Vertex AI | vertex | GCP region and Vertex project ID |
| Azure AI Foundry | azure | Foundry API key and base URL |
Keys are stored locally only (via your OS keychain, under ~/.3xcode/providers/) and are never sent to the backend; only the provider name and your preferred models are registered server-side. Manage keys with 3xcode keys list, 3xcode keys test --provider <provider>, and 3xcode keys delete <provider>.
Automation & AI Agents
Can an AI agent drive 3xcode?
Yes. Every command that could prompt interactively has a flag-based equivalent, and 3xcode commands --json emits a full, structured manifest of every command, argument, and flag, exactly what an agent needs to construct valid calls without hardcoding a command list against one specific CLI version.
A stable, discoverable surface
commands --json is generated from the CLI version actually installed, so an agent (or a script) always sees the real, current set of commands and flags.
No prompts required
Login, file selection, confirmations, and provider setup all accept flags instead of interactive input, so a fully scripted or agent-driven run never blocks waiting on a terminal.
See Automate & Script the CLI for a full walkthrough, including exit codes and a CI example.