Askcodex

askcodex — OpenAI models as a CLI

The binary lives at ~/.local/bin/askcodex. If it is missing, clone https://github.com/JairoTorregrosa/askcodex and run ./install.sh. It authenticates with the credentials codex login already stored — if they are missing, askcodex says so; tell the user to run codex login.

Intent → command

Two global flags, accepted anywhere on the command line, including after the deepest subcommand:

• --json — exactly one JSON document on stdout, nothing else.
• --no-refresh — the command will not rewrite the auth file. Use it for read-only checks.

Prompting

Before writing a prompt — picking a model, choosing a reasoning effort, or phrasing an image prompt — read references/prompting.md. It has the per-model notes (which slug for which job), per-use-case recipes (one-shot Q&A, codegen, extraction, long context, creative), an effort decision table, and the image-prompt structure that works.

Outputs go to /tmp/askcodex/

Save every artifact under /tmp/askcodex/ (mkdir -p /tmp/askcodex first) instead of the working directory, so large outputs never flood the conversation and stay recoverable by path:

• Images: -o /tmp/askcodex/<descriptive-name>.png, then report the path (and send the file if the user should see it).
• Answers you expect to be long: askcodex ask "..." --json > /tmp/askcodex/<name>.json — read back just the parts you need (jq -r .text). Short answers can stream to stdout normally.
• Raw endpoint dumps: askcodex raw ... > /tmp/askcodex/<name>.json.

Never write artifacts into a git repository's tree unless the user asked for the file there.

Gotchas

• Images: one opaque PNG per call, size chosen by the backend. There are no size, quality, transparency, format, or batch flags — the backend ignores those parameters, so askcodex does not offer them. Don't promise a transparent logo or a specific resolution; if the user needs that, askcodex is the wrong path.
• image edit references must be PNG, max 5, passed with -i. askcodex checks the magic bytes locally and refuses a JPEG-renamed-to-.png before spending a billed request.
• askcodex ask streams; the prompt may be - to read stdin to EOF. Under --json nothing prints until the stream completes, then one {"model","effort","text","usage"} document — usage carries the backend's token counts (or null if it sent none). Pick --model from askcodex models slugs; the default is gpt-5.6-sol at medium effort.
• askcodex models --json prints the whole {"models": [...]} envelope, not the bare array — read .models if you want the list.
• askcodex auth refresh rotates the real auth token and rewrites the auth file. Run it when the user asks for it, not as a routine step; "is the auth valid?" is askcodex auth status --no-refresh.
• raw only talks to the backend's own origin. A path like /codex/usage or a full URL on that origin; anything else is refused at parse time — that's expected behavior, not a bug to work around.
• Errors are final. askcodex prints askcodex: error: <message> on stderr and exits non-zero. Report the message as-is instead of retrying in a loop.