Connecting VS Code to NetSuite with SDF
Setting up the SuiteCloud CLI and the VS Code extension, pulling files and objects from the account down to your machine, then sending them back — plus the setup errors that block people most often.
You can write SuiteScript in NetSuite's built-in editor, but there is no change history, no Git, and no easy way to move work from Sandbox to Production. The SuiteCloud Development Framework (SDF) solves all three: the code lives on your machine as an ordinary project and is pushed to the account by command.
Two tools that complement each other
- SuiteCloud CLI for Node.js — the actual engine, installed through npm. Everything can be done from the terminal.
- SuiteCloud Extension for Visual Studio Code — Oracle's official wrapper that surfaces those CLI commands in the Command Palette and the right-click menu.
The extension calls the CLI behind the scenes, so the CLI still has to be installed. When the extension behaves strangely, run the same command from a terminal — the error message there is far clearer.
Prerequisites
| On your machine | In the NetSuite account |
|---|---|
| Node.js on an LTS release | The SuiteCloud Development Framework feature enabled |
| Oracle JDK — the version required by your SuiteCloud release | The Token-Based Authentication feature enabled |
| SuiteCloud CLI installed globally | A role with SuiteScript and SDF Deployment permissions |
Setting up a project
npm install -g @oracle/suitecloud-cli
# Create a project — choose Account Customization Project for
# customising one account rather than building a SuiteApp
suitecloud project:create -i
# Connect to the account; this opens a browser to authorise
cd project-name
suitecloud account:setupWhat is inside an SDF project
project-name/
├── src/
│ ├── FileCabinet/
│ │ └── SuiteScripts/ ← .js files and other assets
│ ├── Objects/ ← custom records, fields, forms, script records
│ ├── AccountConfiguration/ ← account-level preferences
│ ├── deploy.xml ← what actually gets sent
│ └── manifest.xml ← dependencies and required features
└── project.jsonThe split between FileCabinet and Objects matters. FileCabinet holds files — SuiteScript code, images, templates. Objects holds customisation definitions as XML: custom records, custom fields, script records and their deployments. A new SuiteScript only works once both exist: the code file, and the script record object pointing at it.
Two directions people mix up
In SDF, import means pulling from NetSuite down to your machine. Sending the other way is called upload or deploy. Misreading the direction can overwrite local work.
| Goal | CLI command | Direction |
|---|---|---|
| Pull one file from the File Cabinet | suitecloud file:import | NetSuite → local |
| Pull a customisation object | suitecloud object:import | NetSuite → local |
| List the objects in the account | suitecloud object:list | NetSuite → local |
| Send a single file | suitecloud file:upload | local → NetSuite |
| Check without sending | suitecloud project:validate --server | local → NetSuite |
| Send everything in deploy.xml | suitecloud project:deploy | local → NetSuite |
# Take the latest from the account before changing anything
suitecloud file:import --paths /SuiteScripts/ue_sales_order.js
# After editing, send just that file — fast, for iteration
suitecloud file:upload --paths /SuiteScripts/ue_sales_order.js
# Send a complete package including its objects
suitecloud project:validate --server
suitecloud project:deployIn VS Code every one of those is available from the Command Palette under SuiteCloud, and several appear when right-clicking a file in the Explorer. For a small change to a single file, file:upload is far quicker than deploying the whole project.
The errors that come up most
| Symptom | Usual cause |
|---|---|
| Authentication refused during account:setup | Wrong account ID, Sandbox suffix included |
| The CLI fails with no clear message | The JDK version does not match |
| The account does not recognise SDF commands | The SuiteCloud Development Framework feature is off |
| Deploy refused on permissions | The role lacks SDF Deployment permission |
| Deploy fails on dependencies | manifest.xml is incomplete; run project:adddependencies |
| An object fails to create | It references a custom field that does not exist in the target account |