Linux and WSL CLI environments

Back to the Codex learning hub

Goal and two entry routes

On a Linux computer, open its terminal and begin at step two. Windows users should decide whether Linux tooling is needed; native PowerShell can run Codex without WSL. Choose WSL2 for an existing Linux workflow or Linux-dependent project. It is an alternative to Windows CLI, not an automatic migration for every Windows installation error.

Diagram 1 identifies the command environment, 2 installs and enters the Linux project, and 3 verifies files from that environment. Linux home directories, tools and credentials are separate by default. A successful Windows codex --version does not establish installation inside Ubuntu, and WSL authentication alone does not establish sign-in in the Windows desktop client.

Step 1: Windows users verify WSL2

Run this query in Windows PowerShell and inspect the distributions and VERSION column for 2. It is not a Linux-shell command. Preserve an existing WSL2 distribution. The current Codex Linux sandbox does not support WSL1. If your work is in WSL1, back it up and plan conversion with Microsoft's documentation rather than experimenting on its only copy.

wsl --list --verbose

Check winver first: Microsoft’s simplified wsl --install procedure requires Windows 11 or Windows 10 version 2004 (build 19041) or later. Older versions require the official manual installation procedure rather than the command below. If WSL is absent, confirm virtualization/WSL is permitted and follow Microsoft's instructions to run wsl --install in administrator PowerShell. Complete any requested reboot and Linux-user creation. This installs an operating-system environment, not just an npm package, so allow time to interrupt other work. Follow managed-device policy rather than bypassing it.

wsl --install

With several distributions, use wsl --distribution followed by the full name shown in your list, quoted as needed, from PowerShell. Select the distribution before installing. Finding codex in distribution A does not establish its availability in B. If you later return to PowerShell, inspect command resolution again rather than applying Linux installation or file-hash records to Windows.

After setup, select your distribution in Terminal or run wsl from ordinary PowerShell to open the default distribution. With multiple distributions, choose the actual name shown by wsl --list --verbose rather than assuming Ubuntu exists. Once inside, prompts and paths use Linux conventions. All following steps run in that Linux shell.

Step 2: identify the shell, CLI and home directory

uname -s
pwd
printf '%s\n' "$WSL_DISTRO_NAME"
command -v codex
type -a codex

Expect Linux from uname. WSL_DISTRO_NAME identifies the distribution in WSL; an empty value on ordinary Linux is normal. Inspect command -v and type -a for the intended Linux installation. A Windows wrapper under /mnt/c is not evidence of a native Linux installation. Record the source, install inside Linux and verify which command the shell subsequently selects.

For a new installation, verify and run the official standalone command, read the PATH instructions and open a new Linux terminal. Existing npm users can verify node/npm inside the same Linux environment and use npm install -g @openai/codex. Windows Node.js is not a substitute for that Linux setup. Choose one channel and keep updates consistent.

curl -fsSL https://chatgpt.com/codex/install.sh | sh

command -v codex
codex --version
codex --help

Match installer output, executable path and version. If curl, sh or system utilities are missing, prepare them using your distribution's documentation rather than another distribution's package commands. CLI startup does not establish project dependencies or working sandbox execution; the file task checks the next layer.

Step 3: create the exercise in Linux home

For WSL work executed by Linux tools, prefer Linux home such as ~/code. /mnt/c is a Windows filesystem mount, not another name for the same /home project. Leave production repositories in place for this exercise. The block below creates a new folder and stops without overwriting if it exists. Choose a new name if needed. It runs in a subshell; explicitly enter the folder afterward.

(
  set -e
  cd ~
  mkdir 'codex linux lab'
  cd 'codex linux lab'
  printf '%s\n' 'LINUX-CLI-01' > note.txt
  cp note.txt note.original.txt
  pwd
  ls
)

Run the next block only after creation succeeds. A File exists error from mkdir protects prior data; it is not a reason to add sudo. Choose a new directory. After entering, expect two files, LINUX-CLI-01 and matching SHA-256 hashes. This compares identical local bytes, not a required match to Windows file hashes.

cd ~/"codex linux lab"
pwd
cat note.txt
sha256sum note.txt note.original.txt

Step 4: authenticate and read in that Linux environment

codex login
codex login status
codex --sandbox read-only

Wait for each command and follow the actual sign-in flow. WSL may use the host browser, but return to the Linux terminal to verify completion. Without a browser or working local callback, consult codex login --help and the official authentication page. Use codex login --device-auth only when your account and organization permit device authentication. Do not copy Windows credential files into a project as a login fix.

Read note.txt and note.original.txt in the current Linux practice directory. Report the current directory and the exact marker, and check whether both files match. Do not edit, create files, or use external services. Stop and report any missing file or access error.

That is a Codex prompt, not a bash command. Expect the Linux practice directory, LINUX-CLI-01 and an actual read record. Next, request nonexistent note-missing.txt in the same Codex session and expect an explicit absence report without creation. Then use /exit to return to the shell and rerun sha256sum, cat and ls to confirm no changes. Both outcomes connect installation, authentication, location and reading into a verified workflow.

Files, updates and troubleshooting

For slow Linux-tool workloads under /mnt/c, compare a new practice copy in Linux home before moving or deleting the only original. To inspect WSL through File Explorer, use the documented \\wsl$ entry and choose the actual distribution. This accesses Linux files; it does not synchronize two copies. Identify directories through markers and pwd, not matching names alone.

Exit CLI and record the work summary before updating. Use the Linux installer again for standalone, or npm in the same Linux environment for npm installations. Check command -v and version in a new shell. wsl --update updates WSL, not Codex CLI; wsl --shutdown stops running WSL work and is not a routine required Codex installation step.

If the shell can read but Codex cannot, record sandbox startup/access errors, confirm WSL2 and the distribution, and follow permissions rather than disabling sandboxing by default. Missing old sessions may reflect a different distribution, Linux user or CODEX_HOME. This lesson does not share credential directories across environments. Return to CLI basics for editing/restoration, then context handoff.

Back to the Codex learning hub

Read the full description

Three numbered stages: identify the starting point, perform the exercise, and verify the result. Original illustration, not a product screenshot.

• AI tools
• Tutorials
• Codex