alttext-cli

 __  __       __      ___      _
|  \/  |_   _ \ \    / (_)___ (_) ___  _ __
| |\/| | | | | \ \  / /| / __|| |/ _ \| '_ \
| |  | | |_| |  \ \/ / | \__ \| | (_) | | | |
|_|  |_|\__,_|   \__/  |_|___/|_|\___/|_| |_|

MyVision in ASCII Art.

A Node.js CLI + interactive TUI that generates accessibility-friendly alt text from images using the OpenAI API (vision).

• Interactive mode: run alttext (guided prompts)
• CLI mode: run alttext <imagePath> (pipe-friendly: prints alt only)
• Automation-ready: --json returns structured output

---

Table of contents

• Features
• Requirements
• Install
• Quick start
• Usage
• Options
• Output
• Accessibility tips
• Troubleshooting
• Security
• License

---

Features

• ✅ Concise, accessibility-friendly alt text
• ✅ --context to tailor output to where the image is used
• ✅ --long for a longer description (1–3 sentences)
• ✅ Extracts meaningful on-image text into text_in_image when relevant
• ✅ --decorative outputs empty alt ("") for decorative images
• ✅ --copy copies alt text to clipboard (best-effort across platforms)
• ✅ Interactive TUI flow (no args): path → context → options → output → repeat

---

Requirements

• Node.js 18+
• An OpenAI API key in OPENAI_API_KEY

---

Install

Local development (recommended)

git clone https://github.com/sargentJE/Alt-text-Generator.git
cd Alt-text-Generator
npm install

Create your env file:

cp .env.example .env

Set:

OPENAI_API_KEY="your_key_here"

Link the command locally:

npm link

---

Quick start

Interactive TUI:

alttext

CLI mode (prints only alt text by default):

alttext ./photo.jpg

---

Usage

Interactive TUI

Run with no arguments:

alttext

You’ll be prompted for:

• image path (tip: drag & drop into Terminal works well on macOS)
• optional context
• output options (long / json / copy / decorative)
• then you can process another image

CLI mode

alttext <imagePath> [options]

Examples:

alttext ./chart.png --context "Figure in a blog post" --long
alttext ./img.webp --json | jq -r .alt
alttext ./divider.png --decorative
alttext ./img.png --json --out alt.json --quiet
alttext ./img.png --copy

---

Options

Option	Description
-c, --context <text>	Adds usage context (improves relevance/accuracy)
--long	Adds a longer description (1–3 sentences)
--json	Outputs JSON with alt, long, text_in_image, notes
--model <name>	Override model (default: gpt-4o-2024-08-06)
--decorative	Outputs empty alt ("")
-o, --out <file>	Writes output to a file
-q, --quiet	Suppresses stdout (useful with --out)
--copy	Copies the alt text to clipboard (best-effort)
--no-banner	Hides the ASCII art banner in interactive mode
-h, --help	Shows help

---

Output

Default (non-JSON)

Prints only the alt string (great for pipelines):

alttext ./image.png
# -> "Two people standing beside a whiteboard covered in sticky notes."

JSON (--json)

{
  "alt": "Concise alt text here.",
  "long": null,
  "text_in_image": null,
  "notes": null
}

Notes:

• long, text_in_image, and notes may be null when not applicable.
• In non-JSON mode, the tool prints only alt.

---

Accessibility tips

Alt text is best when it:

• is concise and specific
• describes what matters in context (use --context)
• includes essential on-image text when users need it
• avoids filler like “Image of…”

---

Troubleshooting

Missing OPENAI_API_KEY

Make sure you created .env and set your key, or export it:

export OPENAI_API_KEY="your_key_here"

“Not an image (detected mime: …)”

The tool detects file type from the extension. Ensure your image has a standard extension like .png, .jpg, or .webp.

Clipboard doesn’t work on Linux

Install one of:

• wl-clipboard (Wayland, provides wl-copy)
• xclip (X11)

---

Security

• Your API key is read from .env or environment variables.
• Do not commit .env to git.

---

License

MIT