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 your own self-hosted instance.

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

@genfeedai/cli requires Node.js 22.12 or newer. This differs from @genfeedai/create (npx @genfeedai/create my-genfeed), the self-host installer, which requires Node.js 24 (>=24 <25). See Installation Options.

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

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

The CLI’s built-in default API URL points at Genfeed’s hosted API, so on a self-hosted install always tell it where your instance is. A default local install serves the API at http://localhost:3010/v1 and the web app at http://localhost:3000.

Create an API key

In your instance’s web app, create a key in organization settings at /{orgSlug}/~/settings/api-keys (see API Keys). Then log in with it. This is the simplest path and works in CI, containers, and agent runtimes:


gf login --api-url http://localhost:3010/v1 -k gf_live_xxx

Keys must start with gf_live_ or gf_test_. To paste a key interactively instead:


gf login --api-url http://localhost:3010/v1 -i

Without -k or -i, gf login opens a browser and completes a PKCE authorization flow against your instance’s web app (/oauth/cli). The CLI listens on a temporary localhost port, exchanges the returned code for a key, and stores it. The web app origin is derived from the API URL, or you can provide it explicitly when the two origins do not follow the standard api. / app. convention, which includes localhost:


gf login --api-url http://localhost:3010/v1 --app-url http://localhost:3000

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 and interactively when you have several.

You can persist the URL on a profile instead of passing it each time:


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

If you run behind your own domain, use that API URL instead; see Reverse Proxy and HTTPS.

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 built-in default API URL is Genfeed’s hosted API (https://api.genfeed.ai/v1); set api-url to your own instance as shown above.


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 several instances, for example local and staging:


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


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

brands remains an alias for compatibility.

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

Turbo and templates

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


gf turbo create -n 5 -p twitter,linkedin --topics ai,product --style professional
gf turbo list
gf turbo show <id>
gf turbo approve <id> [itemIds...]
gf turbo reject <id> [itemIds...]
gf turbo 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 --api-url http://localhost:3010/v1 -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
Installation Options — run the API the CLI talks to

CLI