Install the OxCode CLI
OxCode also runs in your terminal. This guide takes you from a computer with nothing installed to your first task. You do not need to know Node.js or the terminal. Each step says what to type and what you should see.
Already have Node.js? This is the short version.
# Prints a version. v18 or higher is good. node -v # Installs the oxcode command. npm install -g oxcode-ai # Run it in your project folder. The first time, it asks you to sign in. oxcode
Before you start
The OxCode CLI needs Node.js 18 or later. Node.js is a free program that runs the CLI. You install it once. It also brings npm, the tool that installs the CLI in the next step.
Open a terminal
A terminal is a window where you type commands. On Windows, open the Start menu, type PowerShell and press Enter. On macOS, press Cmd and Space, type Terminal and press Enter. On Linux, open your terminal app.
Check if you already have Node.js
node -vIf it prints v18 or a higher number, such as v22.12.0, you are ready. Go on to Install the CLI. If it says the command was not found, or the number is lower than 18, install Node.js with the steps for your system.
Windows
In PowerShell, run:
winget install OpenJS.NodeJS.LTSOr download the installer from nodejs.org and run it. When it finishes, close the terminal and open a new terminal. A window that was open during the install does not see the new program.
macOS
If you use Homebrew, run:
brew install nodeOr download the installer from nodejs.org and run it. Then open a new terminal.
Linux
Install Node.js with your distribution’s package manager, or follow the steps on nodejs.org. Some distributions ship an older version, so check it after you install.
Run node -v once more. It should now print v18 or higher.
Install the CLI
In your terminal, run:
npm install -g oxcode-aiThe -g means global. It puts the oxcode command on your whole computer, not in one folder. It can take a minute.
Check that it worked:
oxcode --versionIt prints the version you installed. If your terminal says oxcode was not found, see Troubleshooting.
Start OxCode
Open a terminal in your project folder. The easy way: type cd and a space, drag your project folder into the terminal window, and press Enter. On Windows you can also open the folder in File Explorer, click the address bar, type powershell and press Enter.
Then run:
oxcodeThe first time, OxCode shows a sign-in screen. You have two choices.
- Sign in with Google in the browser. This is the default, so press Enter. Your browser opens, you sign in there, and OxCode picks it up in the terminal by itself.
- Sign in with a code. Press c. This is for when no browser can open, such as over ssh. The screen shows a code and a web address. Open the address in any browser, sign in, and type the code there.
OxCode saves your sign-in on this computer, so the next start skips this screen.
The first time you open a folder, OxCode asks: Do you trust the files in this folder? Choose Yes for projects you wrote or trust. If you choose No, OxCode still reads your files and answers, but it asks before it runs anything. You can change this later with /trust.
Now describe the task in plain words, for example: add input validation to the signup form. Press Enter and OxCode gets to work.
Everyday use
The session
oxcode opens a full-screen session of its own. The conversation scrolls above and you type at the bottom. Each step of a run is one short line, and Ctrl + O opens the details of every step. The mouse wheel scrolls.
Type /exit to leave. Your terminal comes back as it was. Your conversations are saved, and oxcode --resume or /resume opens an earlier one. If you want the session to stay in your terminal’s normal scrollback instead, run oxcode --no-app.
Approving changes
OxCode asks before it does anything risky. By default it asks only before a command that could lose work, change your machine, reach your keys or publish something. When it asks, a panel shows the whole command and why it is asking, with these answers:
- Yes runs it this once.
- Yes, and don’t ask again allows that kind of command in this folder. It appears only when OxCode can offer it.
- No does not run it.
Press 1, 2 or 3, or use the arrow keys and Enter. Esc means No. If the command is long, press v to read all of it. Yes is not accepted until the whole command has been on your screen. To make OxCode ask more often, type /approvals ask. Type /approvals auto to go back.
Slash commands
Type / in the session to see every command. These are the ones to learn first.
| Command | What it does |
|---|---|
| /help | Shows the list of commands. |
| /account | Shows who is signed in, your plan and the runs you have left today. |
| /usage | Shows your plan, the runs left today as a bar, when they come back, and what this session has done. |
| /upgrade | Shows your plan and the page where the plans are. You can open it or copy the link. |
| /plugins | Manages plugins: see what is installed, find more and install them. It always asks before it installs or removes anything. |
| /logout | Signs you out. Your conversation is kept. |
/login signs in again. Use it, or run oxcode login in your terminal, when you want to switch to another account. Type @ to pick a file for OxCode to look at.
One task, no session
To run a single task and get the answer back, put the task after the command:
oxcode "add input validation to the signup form"OxCode does the task, prints the answer and exits. You need to be signed in already, so run oxcode once and sign in first. If you see “You are not signed in”, that is why.
Update
To get the newest version, run:
npm i -g oxcode-ai@latestOxCode tells you when a new version is out. About once a day it checks npm in the background. If there is a newer version, it shows one line under the input box, such as Update available 0.11.0 -> 0.12.0: npm i -g oxcode-ai@latest. It never installs anything by itself. Run the command when you are ready, then start oxcode again. oxcode --version shows which version you have. To turn the check off, set OXCODE_NO_UPDATE_CHECK=1.
Troubleshooting
- oxcode is not found, or not recognized. First close the terminal and open a new terminal. A window that was open during the install does not see the new command. If it still fails, check that npm’s global folder is on your PATH. On Windows, run
npm prefix -g. It prints a folder. Search Windows for “environment variables”, choose Edit the environment variables for your account, select Path, add that folder, and open a new terminal. On macOS and Linux, the same folder with/binon the end must be on your PATH. - node is not found. Open a new terminal after you install Node.js. If it still fails, run the Node.js installer again.
OxCode needs Node 18 or newer. Your Node.js is too old. Install a newer one from nodejs.org, open a new terminal and runoxcodeagain.EACCESpermission denied during the install (macOS and Linux). npm cannot write to its global folder. Avoid fixing it withsudo. Install Node.js with a version manager such as nvm or fnm, which keeps Node.js in your home folder, or point npm’s global folder at a folder you own. The npm documentation explains how. Then run the install command again.- You are not signed in. Run
oxcodeonce and sign in on the screen it shows. Then try your task again. - The browser did not come back. Switch to a code on the same screen. OxCode offers it while it waits, and again after 5 minutes.