CLI

@genfeedai/cli is the terminal client for Genfeed. It generates content, publishes and schedules posts, reads analytics, drives workflows, and runs an interactive agent shell — against Genfeed Cloud or a self-hosted deployment.

Package: @genfeedai/cli

Binaries: genfeed and gf (identical; gf is used throughout this page).

Source: packages/cli

Install


bun add -g @genfeedai/cli

Verify the install:


gf --version
gf --help

Node.js 22.12 or newer is required.

Interactive workspace

Run gf with no arguments in a terminal to open the Ink workspace. Plain text continues an agent thread; slash commands perform direct, discoverable operations without leaving the workspace.


› Plan a launch week for our new product
› /brand use Acme Studio
› /image editorial product launch poster
› /workflow run weekly-content
› /balance

The slash is TUI syntax only. Shell commands remain conventional subcommands, so use gf workflow list, not gf /workflow list. A non-TTY invocation with no arguments prints help instead of trying to launch an interactive interface.

Authenticate

Genfeed Cloud

gf login opens a browser and completes a PKCE authorization flow against https://app.genfeed.ai/oauth/cli. The CLI listens on a temporary localhost port, exchanges the returned code for a key, and stores it:


gf login

New users can enter the same PKCE flow at the sign-up screen:


gf signup

gf auth login is the same command under the auth namespace.

After a successful login the CLI validates the key, records your organization, and selects your brand — automatically when you have exactly one, interactively when you have several.

API keys and headless environments

Skip the browser entirely by passing a key. Use this in CI, containers, and agent runtimes:


gf login -k gf_live_xxx

Keys must start with gf_live_ or gf_test_. Create them at API key settings or with gf keys create.

To paste a key interactively instead of opening a browser:


gf login -i

Self-hosted

Point the CLI at your own deployment. The web app origin is derived from the API URL, or can be provided explicitly when the two origins do not follow the standard api. / app. convention:


gf login --api-url https://api.example.com/v1 --app-url https://app.example.com

Headless self-hosted environments can still use gf login -k gf_live_xxx or gf login -i.

You can persist the URL on a profile instead of exporting it each session:


gf config set api-url http://localhost:3010/v1

Session commands


gf whoami          # current user, organization, and scopes
gf logout          # remove stored credentials

Configuration

Configuration lives in ~/.gf/config.json, organized into named profiles with one active profile at a time. The default API URL is https://api.genfeed.ai/v1.


gf config show           # resolved configuration for the active profile
gf config path           # print the config file location
gf config set <key> <value>
gf config reset          # restore profile defaults (--force to skip the prompt)

Settable keys: agent-model, api-key, api-url, brand, org-id, role.

Use profiles to keep separate credentials for cloud, staging, and a self-hosted instance:


gf profile list
gf profile create staging --api-url https://staging.example.com/v1 --api-key gf_test_xxx
gf profile use staging
gf profile set api-url https://staging.example.com/v1

Environment variables

Environment variables override the active profile for the current process.

Variable	Description
`GENFEED_API_KEY`	API key
`GENFEED_API_URL`	API base URL (include the `/v1` suffix)
`GENFEED_TOKEN`	Auth token
`GENFEED_ORGANIZATION_ID`	Organization ID
`GENFEED_USER_ID`	User ID
`GENFEED_AGENT_MODEL`	Default model for `gf chat` and `gf chat send`

Command surface

Every command accepts --json for machine-readable output. Run gf <command> --help for the full option list.

Identity and access

Command	Purpose
`gf login`	Authenticate (browser flow, `-k <key>`, or `-i`)
`gf auth login`	Same login flow under the `auth` namespace
`gf logout`	Remove stored credentials
`gf whoami`	Show current user, organization, and scopes
`gf keys`	Manage API keys

API keys


gf keys list
gf keys create -n "CI publisher" -p content
gf keys rotate <id>
gf keys revoke <id>

create takes a scope preset via -p (mcp, read, content, full) or an explicit --scopes list, plus optional --expires-at, --rate-limit, and --allow-ip restrictions. The secret is printed once, on creation and on rotation.

Brands, balance, and credits


gf brand list                          # list brands
gf brand use <id-or-slug-or-label>     # choose the active brand
gf brand current                       # show the active brand
gf brand show <id>                     # full brand details
 
gf balance                             # current available credits
gf credits packs                       # available top-up sizes
gf credits buy 5000                    # open server-priced Stripe Checkout
gf credits buy 5000 --no-open --json   # return the URL in a headless session
gf credits history --limit 20          # credit ledger
gf credits usage                       # consumption details
gf credits summary                     # billing summary

brands remains an alias for compatibility. Stripe Checkout is hosted by Stripe: the CLI never collects card data and never chooses a price ID. Cryptocurrency checkout is not currently part of the supported surface.

Most content commands accept -b, --brand <id> to override the active brand for a single call.

Generate


gf gen image "A futuristic cityscape at sunset" --model imagen-4 --width 1920 --height 1080
gf gen video "A drone flying over mountains" --model google-veo-3 --duration 10 --resolution 1080p
gf gen article "Write about AI marketing trends" --category marketing
gf gen article-x "Write a founder update thread"

generate remains an alias. Image generation additionally supports references, multiple outputs, seed, creative direction (style, format, mood, camera, lens, scene, lighting), negative prompts, blacklists, tags, automatic model routing and priority, brand/fidelity modes, and prompt templates. Use gf gen image --help for the exact flags.

Shared options: -m, --model, -b, --brand, -o, --output <path> to download the result, and --no-wait to return an ID immediately instead of blocking.

Poll an async job with gf status:


gf status <id>                  # defaults to --type image
gf status <id> --type video
gf status <id> --type article

Batch and templates

Generate many pieces in one job, then review before anything ships:


gf batch create -n 5 -p twitter,linkedin --topics ai,product --style professional
gf batch list
gf batch show <id>
gf batch approve <id> [itemIds...]
gf batch reject <id> [itemIds...]
gf batch cancel <id>

Reusable prompt and workflow templates:


gf template list
gf template create --label "LinkedIn Hook" --purpose prompt --content "Write a hook about {{topic}}"
gf template use <id> --variables '{"topic":"AI workflows"}'
gf template show <id>
gf template popular
gf template suggest --prompt "weekly product changelog post"
gf template delete <id>

Library

Browse generated assets:


gf asset --type image --limit 20
gf asset list --type image --limit 20
gf asset show <id>
gf asset download <id> --output ./asset.jpg
gf job status <id> --type image

library remains an alias.

Publish and schedule


gf publish <ingredientId> --platforms twitter,linkedin --caption "Ship day"
gf publish <ingredientId> --platforms twitter --status draft
gf publish <ingredientId> --platforms linkedin --scheduled-date 2026-09-01T14:00:00Z
 
gf posts list --platform twitter --status published

Calendar and scheduling helpers:


gf schedule calendar --start 2026-09-01T00:00:00Z --end 2026-09-30T00:00:00Z
gf schedule optimal --platform instagram --timezone Europe/Berlin
gf schedule bulk --items '[{"contentId":"...","platform":"linkedin","scheduledAt":"2026-09-02T09:00:00Z"}]'
gf schedule repurpose <id> --platforms tiktok,instagram
gf schedule repurpose-status <id>

Insights and performance

AI-derived recommendations:


gf insights                          # top insights
gf insights times --platform twitter # best posting times
gf insights forecast --topic "agentic workflows" --platform linkedin
gf insights viral --content "Draft post text"
gf insights gaps
gf insights growth --platform instagram

Measured results:


gf performance weekly --top 5 --worst 5
gf performance top --limit 10 --start 2026-08-01T00:00:00Z
gf performance prompts

Agent, threads, and workflows

Start the compatibility readline agent shell (the richer Ink workspace is what gf with no arguments opens):


gf chat
gf chat --thread <threadId>
gf chat --model claude-3-7-sonnet

Send a single non-interactive turn, which is the entry point for external model and tool runners:


gf chat send "Plan a launch week content sequence" --json
gf chat send --thread <threadId> --stdin < prompt.txt

Manage threads:


gf threads list --status active
gf threads show <threadId>
gf threads resume <threadId>
gf threads respond <threadId> "Use the more technical angle" --json
gf threads archive <threadId>

Run workflows:


gf workflow list --limit 20
gf workflow show <id>
gf workflow run <id-or-key-or-label> --inputs '{"topic":"launch recap"}'
gf workflow runs --status completed
gf workflow status <execution-id>

List the canonical tool names available to the agent shell:


gf tools --json

Scripting

--json makes every command pipeable. Combine it with --no-wait to start work and poll separately:


ID=$(gf gen image "Studio product shot" --no-wait --json | jq -r '.id')
gf status "$ID" --json | jq -r '.status'

A full headless sequence:


gf login -k "$GENFEED_API_KEY"
RESULT=$(gf gen image "Professional headshot, studio lighting" --json)
IMAGE_ID=$(echo "$RESULT" | jq -r '.id')
gf publish "$IMAGE_ID" --platforms twitter,linkedin --json

MCP Server — connect Claude Code, Codex, and other MCP clients to the same capabilities
Endpoint Reference — the underlying REST API
Self-host quick start — run the API the CLI talks to

CLI