AzImg CLI

AzImg CLI is a non-interactive tool for Azure OpenAI image generation and editing. The executable command is azimg.

✨ Key features

• Non-interactive by default for agents, scripts, CI, and unattended shells.
• Azure OpenAI image generation and image editing workflows.
• Local config profiles for endpoint and deployment settings.
• Optional manifests with paths, checksums, usage, deployment, and timestamps.
• Installable agent skill that helps AI agents use azimg correctly.

📦 Installation

Supported release platforms:

• Windows x64: win-x64
• Windows ARM64: win-arm64
• macOS Apple Silicon: osx-arm64
• Linux x64: linux-x64

macOS and Linux

curl -fsSL https://raw.githubusercontent.com/Jcardif/azimg-cli/main/install.sh | bash

Windows PowerShell

iwr https://raw.githubusercontent.com/Jcardif/azimg-cli/main/install.ps1 -UseB | iex

Uninstallation

Use the CLI for the normal uninstall path. It removes the installed executable and install metadata while keeping ~/.azimg/config.json.

azimg uninstall --format text

Use full-cleanup when you also want to delete local config and the installed agent skill:

azimg uninstall full-cleanup --format text

Manual uninstall fallback:

macOS and Linux:

rm -f ~/.local/bin/azimg
rm -f ~/.azimg/metadata.json

Windows PowerShell:

Remove-Item "$env:LOCALAPPDATA\Programs\azimg\azimg.exe" -Force
Remove-Item "$env:USERPROFILE\.azimg\metadata.json" -Force

Manual full cleanup:

rm -rf ~/.agents/skills/azimg
rm -rf ~/.azimg

Windows PowerShell full cleanup:

Remove-Item "$env:USERPROFILE\.agents\skills\azimg" -Recurse -Force
Remove-Item "$env:USERPROFILE\.azimg" -Recurse -Force

Agent skill

The CLI ships with an agent skill for AI agents.

It helps them use azimg for image generation and editing. Install it with:

azimg install-skill --format text

The command downloads skills/azimg/SKILL.md from GitHub by default.

It uses the current CLI version tag and reports the source URL.

It saves the skill to ~/.agents/skills/azimg/SKILL.md.

Use --ref main to install the latest committed skill from the default branch.

🔐 Authentication

AzImg CLI uses the current Azure CLI sign-in via az account get-access-token; token storage is delegated to Azure CLI.

# Login via Azure CLI first
az login

# Verify authentication with azimg doctor
azimg doctor --verify-auth

The authenticated identity needs the Cognitive Services OpenAI User role. Assign it on the Azure OpenAI resource.

To assign the role via Azure CLI:

az role assignment create --assignee "<your-user-or-service-principal>" --role "Cognitive Services OpenAI User" --scope "/subscriptions/<sub>/resourceGroups/<rg>/providers/Microsoft.CognitiveServices/accounts/<resource>"

🚀 Usage example

Generate the azimg-cli repository banner:

azimg generate "Generate a banner image 16:9 for a repo for azimg-cli, a command-line tool that generates images with Azure OpenAI." --profile azure-default --count 1 --size 1536x864 --quality high --background opaque --output-format png --output-directory ./output/banner --name-template azimg-cli-banner --write-manifest --format text

This writes the banner image and manifest to ./output/banner.

For long prompts, put the prompt text in a file:

azimg generate --prompt-file ./prompts/banner.txt \
  --profile azure-default \
  --output-directory ./output/banner

Create a manga-style comic page from multiple character references:

azimg edit ./characters/josh.jpg "Create a polished full-page manga comic page using the supplied character reference images as the basis for the characters. Use dynamic black-and-white manga paneling, expressive faces, action lines, speech bubbles with short placeholder text, and a clean weekly-comic layout." \
  --image ./characters/someleze.jpg \
  --output-directory ./test-opt \
  --name-template comic-page \
  --write-manifest \
  --size 1024x1536 \
  --quality high \
  --output-format png

This writes ./test-opt/comic-page.png and ./test-opt/comic-page.manifest.json.

Use --mask-file instead when you want to constrain an edit to part of the first input image:

azimg edit ./room.png "Replace only the couch with a red velvet sofa" \
  --mask-file ./masks/couch-mask.png \
  --output-directory ./test-opt

Use both together when the first image is the canvas, --image provides visual references, and --mask-file marks where the first image should change.

⚙️ Configuration and common settings

The default configuration file is ~/.azimg/config.json. Run azimg config init --force, or pass values up front so no manual edit is needed. The default output folder is azimg-output, resolved relative to the directory where you run azimg.

azimg config init --force --profile azure-default --deployment gpt-image-2 --endpoint https://your-resource.openai.azure.com/

{
  "schemaVersion": 1,
  "defaultProfile": "azure-default",
  "profiles": {
    "azure-default": {
      "deployment": "gpt-image-2",
      "endpoint": "https://your-resource.openai.azure.com/"
    }
  }
}

📚 Command reference

Command responses are JSON by default. Add --format text when you want human-readable output.

Run azimg <command> --help for the canonical help text. Commands below omit the leading azimg unless the command is global.

Command	Purpose	Required input
--help	Show top-level help.	None.
<command> --help	Show command help.	Command name.
generate	Generate images.	<PROMPT> or --prompt-file <TXT>.
edit	Edit images.	Image plus <PROMPT> or --prompt-file <TXT>.
doctor	Validate config and output setup.	None.
config or config show	Print the current config.	None.
config init	Create a starter config.	Optional profile values.
config set-default-profile	Set default profile.	--profile <NAME>
install-skill	Install the AzImg agent skill.	None.
update check	Check for a newer release.	None.
update or update apply	Install the selected release.	None.
uninstall	Remove the installed executable.	None.
version	Print CLI and bundled skill version information.	None.

Profile, Azure, and output options

Use these with generate, edit, and doctor for per-run settings.

• -p, --profile <NAME>: Use a named profile from the config file.
• --config <PATH>: Read a config file other than ~/.azimg/config.json.
• --deployment <NAME>: Override the Azure OpenAI deployment name.
• --endpoint <URL>: Override the Azure OpenAI endpoint.
• -o, --output-directory <PATH>: Set where generated files are written for this run.

Image generation and edit options

Use these with generate and edit.

• --prompt-file <PATH>: Read the generate or edit prompt from a text file instead of passing <PROMPT> inline. Use this for long prompts; do not combine it with a positional prompt.
• --count <N>: Number of images to create, from 1 to 10.
• --size <WIDTHxHEIGHT>: Image size, such as 1024x1024.
• --quality <auto|low|medium|high>: Requested image quality.
• --background <auto|opaque|transparent>: Requested background mode.
• --output-format <png|jpeg|webp>: Saved image format.
• --output-compression <0-100>: Compression level for supported formats.
• --end-user-id <ID>: Optional user identifier passed to the service.
• --name-template <TEMPLATE>: File name template.
• Tokens: {timestamp}, {id}, {slug}, {index}, and {profile}.
• --write-manifest: Write a manifest JSON file beside the images.
• --image <PATH>: Additional input/reference image or image folder for edit. Use this for character, product, style, logo, or other visual references. Repeat this option to include multiple files or folders.
• --mask-file <PATH>: PNG mask for edit only. Use this to target where the first input image should change. The mask applies to the first input image.

For edit, the positional input can be an image file or a folder. Image folders expand to supported image files in deterministic order. Supported image extensions are .png, .jpg, .jpeg, and .webp. Local non-PNG edit inputs are normalized to temporary PNG files before upload. Masks are not normalized; provide mask files as PNGs with the expected alpha channel.

Use --image when the extra file should influence the result visually. Use --mask-file when the extra file is a transparency mask that identifies an edit region. They can be combined: the mask selects the area on the first image, and additional --image inputs provide references for what to put there.

Config options

• config defaults to config show.
• config init --force overwrites an existing config file.
• config init accepts optional --profile, --deployment, and --endpoint values.
• Image output defaults to azimg-output under the command's current directory unless generate or edit gets --output-directory.
• config set-default-profile --profile <NAME> changes the default profile.
• --path <PATH> reads or writes a specific config file.
• --action <ACTION> selects the action by option instead of position.

Update options

• update defaults to update apply.
• update install is an alias for update apply.
• --version <TAG> selects a specific release instead of the latest release.
• --install-dir <PATH> selects the directory that contains azimg.
• --manifest-url <URL> uses an explicit release manifest.
• --dry-run previews update work without changing files.
• --force reinstalls even when the selected release is already current.

Version output

• version prints both the AzImg CLI version and the bundled AzImg agent skill version.

Uninstall options

• uninstall removes the executable and install metadata, but keeps ~/.azimg/config.json.
• uninstall full-cleanup also removes ~/.azimg and the installed AzImg agent skill.
• --install-dir <PATH> selects the directory that contains azimg.
• --dry-run previews uninstall work without changing files.

Agent skill options

• install-skill downloads and installs the AzImg skill.
• --install-dir <PATH> selects the agent skills root directory.
• --ref <BRANCH|TAG|SHA> selects the GitHub ref for SKILL.md.
• --source-url <URL> downloads SKILL.md from an explicit URL.
• --dry-run previews the download source and save path.
• --force overwrites an existing different SKILL.md file.

Output formatting

• --format json is the default for structured command output.
• --format text prints human-readable output.

🧑‍💻 Development

For development, restore dependencies, build, test, and smoke-test the CLI:

git clone https://github.com/Jcardif/azimg-cli.git
cd azimg-cli

dotnet restore AzImg.Cli.slnx
dotnet build AzImg.Cli.slnx --configuration Release --no-restore
dotnet test AzImg.Cli.slnx --configuration Release --no-build

dotnet run --project src/AzImg.Cli doctor
dotnet run --project src/AzImg.Cli version

📝 Release notes

Release notes live in docs/release-notes/<tag>.md.

⚖️ License

This project is licensed under the MIT License.