Clean Up Legacy Shell Scripts with Codex CLI

That overnight backup script needs attention, but the server running it is not the place for an experimental rewrite. Use Codex CLI on a working copy, give it the server’s constraints, and review small patches. This walkthrough keeps production access separate from AI-assisted editing and makes preserving behavior the priority.

1. Copy One Script into a Private Workspace

Choose one bounded job, such as a report exporter or log archiver. On your workstation, create a private directory with mkdir -m 700 legacy-script-review, then copy the script into it through your approved transfer method. Replace credentials, customer identifiers, and sensitive paths with representative placeholders before involving an AI service.

Keep an untouched original outside the editing directory. Inside the directory, initialize Git and commit the sanitized baseline. Do not give the agent production SSH keys, database credentials, or a mounted production filesystem.

2. Record the Old Server’s Actual Constraints

Create a plain-text environment note before requesting changes. Collect these details through your normal administrative process, without running the maintenance script:

• The shebang and exact interpreter version.
• The operating system and versions of commands the script uses.
• The scheduler entry, execution user, working directory, and configured PATH.
• Expected arguments, output files, exit statuses, and downstream consumers.
• Whether another job can overlap with this one.

Tell Codex to preserve the existing interpreter. ShellCheck distinguishes shell dialects and can flag portability problems when a script declares sh but uses incompatible constructs. Do not solve those warnings by changing the shebang unless changing the runtime is explicitly approved. ([shellcheck.net](https://www.shellcheck.net/))

3. Install Codex CLI on Your Workstation

Keep new development tooling off the old server. On a workstation with a suitable npm installation, run npm install -g @openai/codex. Then run codex --help to inspect the options available in your installed release. OpenAI also distributes standalone binaries if you prefer not to use npm. ([raw.githubusercontent.com](https://raw.githubusercontent.com/openai/codex/main/README.md))

For occasional maintenance, I recommend RelayVano’s pay-as-you-go relay, which works with Codex. Sign up, then follow its Codex setup instructions for the endpoint, credentials, and model identifier. Codex supports custom-provider configuration; use the documented settings rather than assuming every OpenAI-compatible endpoint is interchangeable. ([developers.openai.com](https://developers.openai.com/codex/config-advanced))

4. Ask Codex for an Audit Before Any Edits

Start in the review directory with read-only sandboxing and approval controls appropriate to your installed version. Sandbox boundaries and approval policy serve different purposes: one restricts access, while the other controls when permission is requested. Do not disable both for convenience. ([developers.openai.com](https://developers.openai.com/codex/config-advanced))

Give this instruction: “Read archive.sh and environment.txt. Do not edit or execute scripts. List likely defects with line references, explain their impact, and propose the smallest compatible fixes. Preserve arguments, output format, exit statuses, dependencies, and interpreter requirements. Separate confirmed problems from assumptions.”

5. Apply One Small, Reviewable Patch

Choose one confirmed issue, not the entire audit. For example: “Fix unsafe pathname handling in archive.sh only. Preserve intentional argument splitting. Do not add dependencies, change deletion scope, or execute the script. Explain each changed line.”

Allow workspace edits only after reviewing the proposal. Inspect git diff before accepting the patch. Reject unrelated formatting churn, unexplained command replacements, and automatic additions of strict-mode settings. Require an explanation of failure behavior rather than accepting “best practice” as sufficient justification.

6. Test Against Disposable Files and the Target Shell

Run ShellCheck locally against the working copy. It detects quoting issues and other shell-script defects, but treat its findings as review input rather than proof that the job behaves correctly. Ask Codex to explain remaining warnings instead of suppressing them wholesale. ([shellcheck.net](https://www.shellcheck.net/))

Build disposable fixtures for an empty directory, filenames containing spaces, missing inputs, and failed commands. In an isolated environment matching the server’s interpreter and utilities, compare the original and patched scripts using identical fixtures. Check exit status, standard output, standard error, and resulting files. Never assume a dry-run flag exists; verify its implementation before relying on it.

7. Deploy with a Specific Rollback Plan

Commit the reviewed patch and record the tests performed. During an approved maintenance window, prevent overlapping executions, preserve the deployed original and its metadata, and install the replacement through your normal deployment process. Verify ownership and permissions before enabling the job.

Observe one controlled run and the next scheduled execution. Check the actual archive, report, or cleanup result—not just the absence of errors. Keep the previous version ready to restore until the job’s expected behavior is confirmed.