fx ask

fx ask runs one noninteractive request and exits. Connect an account, then run it from your project directory:

$fx ask "explain what this repository does"

Pass a prompt to fx ask

Pass the prompt as command arguments. In a shell script, printf can send generated prompt text to fx ask through standard input (stdin):

$printf "summarize src/core\n" | fx ask

Put -- before a prompt that starts with a dash; every argument after it is prompt text.

Use --image <path> to attach an image. Repeat the flag to attach multiple images.

Use --system <text> to replace fx's built-in system prompt for one request. Project instructions, such as AGENTS.md, still apply.

$fx ask --image ./ui.png "describe this interface"

See Vision for supported formats and image routing.

Choose the model

Use --model for one request:

$fx ask --model <model-id> "Review this change"

Add --effort high or --fast if the model supports them. For a supported OpenAI model through AI Gateway, --ultrafast requests the higher-priced Ultrafast tier instead.

The flags do not change your saved defaults. Use --provider <name> when the request should use another provider: gateway, codex, grok, or the name of a custom connection. Setting FX_PROVIDER does the same for every run.

For AI Gateway, --provider-order sets a routing preference and --provider-strict prevents fallback outside it. See AI Gateway routing.

Request Ultrafast

Ultrafast uses a higher-priced OpenAI service tier. Select a model whose AI Gateway catalog advertises Ultrafast pricing, then opt in for one run:

FX_PROVIDER=gateway fx ask --model openai/gpt-6-astra --ultrafast "Review this change"

Use --no-ultrafast to disable a profile or resumed-session request. These flags override FX_ULTRAFAST and leave saved defaults unchanged. --fast and --ultrafast turn each other off, so when you pass more than one speed flag, the last one wins.

If Gateway does not confirm the requested tier, fx writes a warning to stderr. Neither a successful run nor ultrafast_requested in fx status --json proves that the provider served Ultrafast.

Override a setting for one request

Use --config key=value to change a setting for one request without saving it. It takes the same keys and values as fx config set:

$fx ask --config max_agent_steps=20 --config fast_mode=on "fix the failing test"

Repeat --config for each setting. If a key appears twice, the last value wins. A --config value replaces the one in your settings files and .fx.json, but a dedicated flag such as --no-fast and an environment variable such as FX_MAX_AGENT_STEPS still take precedence.

--config refuses the keys that fx config set refuses, such as permission_mode and model choices. Use --permission-mode or --model for those. Interactive sessions don't take --config; change their settings with /settings.

Use fx ask in scripts

For shell scripts and CI, redirect standard output (stdout) to receive raw assistant Markdown. Progress and diagnostics remain on standard error (stderr). Add --quiet to print no assistant text when only the exit status matters; --json takes precedence over it.

In a terminal, --no-color keeps the layout but drops colors and hyperlinks. Setting NO_COLOR or TERM=dumb does the same.

Use --json when a program needs structured fields instead of Markdown:

$fx ask --json "summarize the current changes"

The command returns one JSON object:

{
  "output": "Assistant Markdown",
  "final_output": "Final assistant response",
  "exit_code": 0,
  "model": "provider/model-id",
  "resolved_provider": "bedrock",
  "session_id": "session-id",
  "steps": 1,
  "usage": {
    "input_tokens": 1200,
    "output_tokens": 450
  },
  "tool_calls": [
    {
      "name": "read_file",
      "status": "success"
    }
  ]
}

exit_code matches the command's exit status: 0 on success, 1 when the request fails, and 2 for a usage mistake, such as an unknown flag or --no-save with --resume. A failure can include an error field with the error's name. Tool calls always include name and status; some tools include additional result fields.

output includes the assistant text produced during the request. final_output contains the completed final response, or an empty string when no final response completed.

resolved_provider identifies the AI Gateway provider that served the last model request. It is null when the provider does not report routing.

usage.input_tokens and usage.output_tokens sum the counts reported by main-agent completions, including usage recorded before an error. A count is null when no completion reported it; reported zero remains 0.

When the provider reports caching, usage.cache_read_tokens and usage.cache_write_tokens include its cached-read and cache-write counts. These fields are omitted when the provider does not report them. These totals exclude subagent, helper-model, and provider-tool usage. Use fx usage for the usage and spend your provider reports.

When fx had to retry or stop the last model request, recovery reports how it ended. Its state is recovered after a retry succeeded, failed when the request ended on an error, or need_user when it needs you. attempt counts the sends, message carries fx's status text when there is one, and a need_user result names what it needs in need, such as quota, content_filter, rejected, or too_long. When the provider refuses your credential, auth_failure names the credential's source, such as fx login or AI_GATEWAY_API_KEY, the reason, and the http_status when there is one.

In a script, check the command's exit status before using the reply. This example needs jq:

#!/bin/sh
result=$(mktemp)
trap 'rm -f "$result"' EXIT

if fx ask --json --no-save "Summarize this repository without editing files" > "$result"; then
  jq -r '.final_output' "$result"
else
  status=$?
  cat "$result" >&2
  exit "$status"
fi

Add --no-save for a run that should not create a session. In JSON output, session_id is an empty string. --no-save cannot be combined with --resume.

Use --timeout <seconds> to cap how long each shell command the agent runs can take.

When the agent starts subagents, fx ask waits until every one of them has finished. Each subagent's report runs as another turn before the command exits. Subagents need a saved session, so a --no-save run can't start them.

Retries and requests that need you

fx ask retries network and provider failures like the interactive shell, and prints each wait to stderr, such as [notice] Gateway error · next try in 8s · attempt 4. It keeps retrying until the request goes through. Press ctrl+c to stop it, and the shell reports exit status 130, or 143 after SIGTERM. With --json, an interrupted run writes no result.

A reply that runs out of output tokens before any text is sent again once, as in the interactive shell. See A reply runs out of output tokens.

fx ask can't wait for you. When a request needs you, such as when you're out of credits, a content filter blocks it, the provider rejects it, the conversation is too long for the model, or the provider refuses your credential, the run ends at once with exit status 1 and the reason on stderr. With --json, the result has "exit_code": 1.

Continue a session with fx ask

Use --resume last to continue the latest session for the current workspace:

$fx ask --resume last "now add tests"

You can pass a session ID instead of last. See Sessions to inspect sessions or recover an interrupted response.

Handle permissions in noninteractive runs

Set the permission mode for one request with --permission-mode ask, auto, or full-access, or the shorter --ask, --auto, and --full-access. Your saved mode stays the same.

Saved permission rules apply to fx ask. In a terminal, actions that require approval can prompt on stderr.

With --json or --quiet, add --prompt-permissions to allow those prompts. This requires terminal input; piped or redirected input cannot receive approval prompts.

In auto mode, a security concern holds the action and returns guidance to the agent without asking you for approval. --full-access disables fx permission checks for the run.

An interrupted run exits with code 130. See Troubleshooting when a run ends before the tool executes.

Run fx ask --help for the complete flag reference.