makefx 1.3.0 → 1.5.0

package/README.md

@@ -1,179 +1,64 @@
 # makefx
 
-Command-line interface for [Make Effects](https://makefx.app), an AI media
-workspace for game assets, variants, references, and lineage.
-
-`makefx` lets local developers, scripts, and coding agents create and manage
-website-backed assets from the terminal: generate images, audio, and video;
-upload local media; inspect variants; download outputs; watch real-time space
-events; and curate selected variants.
+Command-line interface for [Make Effects](https://makefx.app).
 
 ## Install
 
 ```bash
 npm install -g makefx
-makefx --version
-```
-
-Requirements:
-
-- Node.js 20 or newer
-- A Make Effects account at https://makefx.app
-
-The npm package installs a bundled executable and does not declare runtime
-dependencies.
-
-## Quick Start
-
-```bash
 makefx login
-makefx spaces create "My Game Assets" --init
-
-makefx generate "A cozy pixel-art market background" \
-  --name "Market Background" \
-  --type scene \
-  -o art/market.png
-
-makefx audio sfx generate "A crisp magical item pickup" \
-  --name "Item Pickup" \
-  -o audio/item-pickup.wav
-
-makefx video generate "A looping idle animation for a tiny robot" \
-  --name "Robot Idle" \
-  --type animation \
-  --duration 6 \
-  --resolution 1080p \
-  --tier fast \
-  -o video/robot-idle.mp4
-```
-
-## Authentication
-
-```bash
-makefx login
-makefx logout
-```
-
-`login` opens a browser-based sign-in flow and stores CLI credentials in the
-user config directory. Credentials are separate from project bindings and are
-not written into your repository.
-
-## Project Binding
-
-Bind the current directory to a Make Effects space:
-
-```bash
-makefx init --space YOUR_SPACE_ID
-```
-
-This writes `.inventory/config.json` with the target environment and space ID.
-It does not store assets, prompts, media files, provider keys, or auth tokens.
-Inside an initialized project, commands can omit `--space` and `--env`.
-
-The CLI defaults to production at `https://makefx.app`. Use `--env stage` for
-staging, or `--local` for a local development server.
-
-## Common Workflows
-
-Inspect and download tracked assets:
-
-```bash
-makefx assets
-makefx assets show ASSET_ID --json
-makefx assets download VARIANT_ID -o references/variant.png
+makefx spaces create "My Game" --init
 ```
 
-Upload local media:
+## Create media
 
 ```bash
-makefx upload hero.png --name "Hero Character" --type character
-makefx upload theme.mp3 --name "Theme Music" --type audio
-makefx upload cutscene.mp4 --name "Cutscene" --type video
+makefx models list --available
+makefx image generate "A painted market" --name "Market" --type scene -o market.png
+makefx video generate "A slow push through the market" --name "Push" --type animation -o push.mp4
+makefx audio sfx generate "Wooden coin pickup" --name "Pickup" -o pickup.wav
 ```
 
-Refine or derive from references:
+Generate creates a new asset. Regenerate creates a sibling from the source
+variant's stored recipe and activates it on success by default:
 
 ```bash
-makefx refine --variant VARIANT_ID "make it evening, with warmer lights" \
-  -o art/market-evening.png
-
-makefx derive \
-  --refs CHARACTER_VARIANT_ID,BACKGROUND_VARIANT_ID \
-  --name "Hero In Market" \
-  --type scene \
-  "Place the hero naturally in the market" \
-  -o art/hero-market.png
+makefx image regenerate IMAGE_VARIANT_REF "Warmer light"
+makefx video regenerate VIDEO_VARIANT_REF "Slower camera"
+makefx audio speech regenerate AUDIO_VARIANT_REF "Softer delivery"
 ```
 
-Compare and choose outputs:
-
-```bash
-makefx variants star VARIANT_ID
-makefx variants rate VARIANT_ID approved
-makefx assets set-active ASSET_ID VARIANT_ID
-```
+Use `--no-activate` to keep the current active variant. Retry a transiently
+failed attempt in place with `makefx variants retry VARIANT_REF`.
 
-Watch real-time space activity:
+## Manage assets
 
 ```bash
-makefx listen --space YOUR_SPACE_ID
-makefx listen --space YOUR_SPACE_ID --json
+makefx assets list --query "hero"
+makefx assets show ASSET_REF --json
+makefx assets upload hero.png --name "Hero" --type character
+makefx assets download VARIANT_REF -o hero.png
+makefx assets delete ASSET_REF --yes
+
+makefx variants show VARIANT_REF --wait
+makefx variants update VARIANT_REF --starred true --rating approved
+makefx variants activate VARIANT_REF
+makefx variants delete VARIANT_REF --yes
 ```
 
-## Agent And Script Usage
-
-Many commands support `--json` for stable machine-readable output. Use JSON
-outputs for automation instead of parsing human-readable tables.
+## Collections
 
 ```bash
-makefx spaces create "Agent Test Space" --init --json
-makefx assets --json
-makefx runs show --latest --debug --json
+makefx collections create "Main Cast" --kind cast
+makefx collections add COLLECTION_ID ASSET_REF --role hero
+makefx collections add COLLECTION_ID VARIANT_REF --role style-reference
+makefx collections remove COLLECTION_ID VARIANT_REF
 ```
 
-Debug run manifests are local troubleshooting traces for generation commands:
+Commands follow `noun verb`. Public asset and variant arguments are compact
+refs. JSON output does not expose raw database IDs, storage keys, jobs, request
+IDs, or runs. Retired commands and aliases are not redirected.
 
-```bash
-makefx runs --debug
-makefx runs show --latest --debug
-```
+Run `makefx --help` or `makefx <noun> --help` for current options.
 
-The website remains the source of truth for spaces, assets, variants, recipes,
-lineage, and stored media.
-
-## Command Groups
-
-| Command | Purpose |
-|---------|---------|
-| `login`, `logout` | Manage CLI authentication |
-| `spaces`, `init` | Create spaces and bind local projects |
-| `generate`, `refine`, `derive`, `batch` | Generate image assets |
-| `audio` | Generate speech, dialogue, music, and sound effects |
-| `video` | Generate, refine, and derive video assets |
-| `upload` | Upload local media files and return Space IDs for chaining |
-| `assets`, `variants` | Inspect, download, curate, retry, or delete outputs |
-| `listen` | Stream real-time space events |
-| `runs` | Inspect local debug manifests |
-| `usage` | Inspect platform storage and workflow consumption |
-| `spend` | Inspect admin provider cost summaries |
-| `billing` | Inspect billing sync and operational status |
-
-Run `makefx --help` or `makefx help <command>` for command-specific options.
-
-## Troubleshooting
-
-- If a command says you are not authenticated, run `makefx login`.
-- If a command cannot find a space, run `makefx init --space YOUR_SPACE_ID` or
-  pass `--space YOUR_SPACE_ID`.
-- If a generation command times out after creating a variant, resume with
-  `--follow VARIANT_ID` and the same output path.
-- If automation needs stable output, add `--json` where supported.
-
-## Links
-
-- App: https://makefx.app
-- CLI docs: https://makefx.app/docs/cli
-- Media generation guide: https://makefx.app/docs/media-playbooks
-- Source: https://github.com/krasnoperov/inventory
-
-Version: 1.3.0
+Version: 1.5.0