Make file uploads and downloads easier to discover

[saioai]

The existing upload alias requires --file; metadata and contents use retrieve and content.
This adds a plain upload path, get for metadata, and download for contents.
Help shows the workflow and gives runnable examples.

This inherits the merged output, stdin, and save policies from #392 and #395.

What changes

• Upload accepts one quoted local path and keeps purpose explicit.
• Files help lists upload, get, and download in workflow order.
• Shell completion supports the first upload path and preserves literal leading @ filenames.
• Bash completion also preserves colon-separated filename prefixes and Readline's replacement suffix.
• Interactive uploads show returned values and a safely quoted, read-only metadata command.
• Suggestions reuse the executable or development checkout, including go run and scripts/run.
• Suggested commands preserve the selected project, organization, and safe base URL. Sensitive overrides suppress the suggestion.
• Error-output options leave successful upload receipts unchanged. Processing errors retain complete details through JSON inspection.
• Malformed known receipt fields use complete response output. Existing null values and large integer timestamps remain supported.
• Interactive get shows complete metadata, full IDs, and UTC timestamps.
• Existing names, flags, machine output, extraction, and download bytes remain available.

Commands

get and download are new routes. The existing upload route gains positional paths.

openai files --help
openai files upload "upload space.txt" --purpose user_data
openai files get file-example
openai files download file-example --output "downloaded copy.txt"
openai files download file-example > copy.txt
openai files get file-example --format json  # complete metadata for scripts
cat upload.bin | openai files upload --file - --purpose user_data

Use one positional path or --file PATH. create, retrieve, content, -o, and extraction options remain available.
Paths are literal. Quote a leading @ in PowerShell, or use ./@name.
Reload an existing completion adapter after updating the CLI.

Receipts and readable timestamps require terminal stdout and stderr, text/auto output, and no extraction or raw output.
--quiet suppresses the upload receipt and retains selected metadata.
The suggested inspection command never selects a download destination or overwrites the upload source.
Keep the same environment when copying it; credentials are never included in suggestions.
Development hints retain their checkout with go -C CHECKOUT run ./cmd/openai.

After an uncertain upload, inspect its known ID or recent same-project files before uploading again.
Upload acceptance does not imply processing completion. Streamed uploads do not retry automatically.
The Files recovery guide gives concrete recovery steps.

Code

pkg/custom adds routes, request-context capture, and terminal presentation over existing decorated handlers.
pkg/transformers formats file timestamps without changing machine data.
internal/autocomplete opts upload into first-path completion and preserves literal filenames across four shell adapters.
internal/clihelp keeps fallback example notes out of command-owned examples.
Files receipt hints can follow one recognized Go parent through platform process metadata.
Unknown callers, lookup errors, cancellation, or unavailable checkout paths omit the optional hint.
Image and setup callers keep their existing shell detection.
Existing terminal escaping, shell quoting, input handling, save policy, and download code remain in use.
No new package, external dependency, generated-source change, or startup change is required against main.

Tested

Candidate: bcd5af5 against main 866d8770.
Its complete source tree matches tested 48aee722; the final merge changes ancestry only.
Local checks used Go 1.26.9 on macOS arm64 with synthetic loopback APIs.
The latest two findings reproduced in eight public processes before correction.
Independent review checked 3ae27da and executed 31 corrected public processes.
That matrix covered 24 uploads and seven metadata requests.
go run and copied hints passed through Bash, zsh, fish, and PowerShell on macOS.
scripts/run passed in Bash and zsh.
An absolute scripts/run invocation remained copyable from outside the checkout. Unknown wrappers did not use a misleading SHELL value.
Malformed, nullable, omitted, signed, and large fields retained their expected output, including a 17 MiB fallback.

At 3ae27da, custom/transformer checks passed 165 results, public Files/help passed 109, and manpage integration passed 18.
None of those runs skipped tests.
Windows and Linux custom-package test compilation passed at 3ae27da. Native ancestry checks remain unverified on those systems.
At runtime 10c10cb, eight independent binary probes passed, including partial-page and receipt-write failures.
That composition passed 128 public Files/local-utility results and 14 additional output/routing results.
The custom run passed 193 results; five unavailable-shell checks passed after adding the existing cached shells to PATH.
That focused rerun passed 29 results without skips.
Go module verification passed. The trusted budget passed with 21/1000 custom lines against current main 866d8770.
Earlier focused vet passed at 3ae27da.
Earlier Bash completion coverage passed 74 results at 520dc58; the completion source remains unchanged.
The earlier three findings retain their separately recorded before/after and context/byte-preservation evidence.
The previous published head ae2ad9e passed hosted tests, builds, platform help, permissions, cancellation, and baseline checks.
See the CI run and platform help run.
Current-head tests, builds, CodeQL, platform help, permissions, cancellation, and baseline checks passed.
Both trusted main-budget statuses passed; three conditional queue jobs skipped.
See the main-based CI run.
At 48aee722, the final table-policy update passed 55 focused results and seven public Files results, with zero skips.
Independent review confirms all 44 Files feature files remain unchanged through the parent update and final main alignment.
Live API acceptance and native Windows Files workflows remain unverified.
PowerShell execution on macOS does not establish Windows filesystem behavior.

The inherited save policy stages explicit ordinary downloads and reports successful saves on stderr.
Quiet and structured error modes suppress optional save receipts; receipt-write failures return nonzero after retaining completed files.
Final local copies remain non-atomic. Redirection and automatic or special destinations can retain partial output.
Malformed HTTP 200 metadata can still return success. The guide explains these limits without promising rollback.

Demo

macOS arm64, Bash, Menlo 18px, terminal replay, and a synthetic loopback API.
Before: Output production 7901147. After: Files 2d482e3.
The recorded ordinary workflow remains unchanged in this candidate.
Separate public-process checks cover the later development-launcher and malformed-response corrections.
Workflow uses 110×46 cells; discovery uses 110×54 cells.

The workflow verifies twelve requests and eight exact text/binary download comparisons.

Before:

After:

Command discovery verifies workflow ordering, runnable examples, and zero API requests.

Before:

After:

Recording recipes.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 64ed67577a

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[markstuart-oai]

Reviewed 64ed67577a143aee79078d4d5e1badbb01b13f43 against stacked base cd1449a5cbfe582147e61a8a89e456c7367f1ffb. I confirmed the existing source-overwrite and request-context findings. Those receipt issues need fixes before approval. I added one separate P3 comment for Bash completion of filenames containing colons.

The aliases, explicit upload purpose, machine-output paths, receipt format gates, and UTC metadata projection were otherwise consistent with the stated contracts. Hosted test, build, artifact, lint, platform-help, cancellation, permission, and Castiron baseline checks passed. This was a source-only review; I did not run local tests, native Files workflows, recordings, or live API calls.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5b0fe1fa89

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[jbeckwith-oai]

Reviewed the Files workflow against its recorded Output base, including command cloning and positional paths, receipt validation, request-context preservation, shell discovery and quoting, metadata rendering, and completion adapters. No blocking findings; the previously reported issues appear addressed.

On the exact head, public synthetic Files workflow/receipt tests, custom File tests, focused Bash and positional completion tests, all transformer and CLI-help tests, focused vet, and changed-file gofmt checks pass. Disabling timestamp-shape validation caused TestFileReceiptKnownFieldShapes to reject the mutation; restored source passed. Hosted checks pass.

The broader custom-package attempt hit existing shell-startup fixtures reporting “protected or unreadable extended metadata” in this sandbox; the relevant focused suites passed. Native Windows/Linux shell ancestry was not independently exercised.

[github-actions]

Castiron custom code

Evaluated main: 866d8770c00c331bf3630b05f2a76870110d2896.

✅ No new custom-code files detected.

2 mixed files remain; 0 existing customizations changed.

Compared 866d8770c00c → bcd5af538bf2. Generated baselines verified.

2 existing customizations unchanged

• pkg/cmd/adminorganizationcertificate.go
• pkg/cmd/audiovoice.go

A changed generated baseline means this report cannot reliably identify which handwritten lines changed.

Inspect the custom-code diff

Download the exact patch produced by this run (requires repository access):

gh run download 37960744096 --repo openai/openai-cli \
  --name castiron-custom-code-37960744096-1 --dir /tmp/castiron-custom-code-37960744096-1
git apply --stat /tmp/castiron-custom-code-37960744096-1/custom-code.patch
cat /tmp/castiron-custom-code-37960744096-1/custom-code.patch

Or reproduce it from an SDK checkout containing the vendored reporter:

git fetch --no-tags origin 866d8770c00c331bf3630b05f2a76870110d2896 bcd5af538bf254c80dd5884a1c1cbbb37389bc96
python3 scripts/castiron/custom_code_report.py report \
  --base 866d8770c00c331bf3630b05f2a76870110d2896 \
  --head bcd5af538bf254c80dd5884a1c1cbbb37389bc96 --fetch --require-head-hash --public \
  --out /tmp/castiron-custom-code-bcd5af538bf2
cat /tmp/castiron-custom-code-bcd5af538bf2/custom-code.patch

This is the current full custom patch for mixed files, not an attribution of only the handwritten lines changed by this PR.

Full report and patch