FruxonDocs

CLI

Build, test, and ship Fruxon agents from your terminal — author drafts, deploy revisions, wire integrations, and inspect executions. Ergonomic for humans and AI-agent drivers.

The fruxon command ships with the Python SDK (pip install fruxon) and turns Fruxon into a terminal-first authoring workflow: sign in once, discover the surface, author and test drafts, deploy revisions, wire integrations and the agent network, and inspect any past execution. Designed to be ergonomic for humans AND for AI-agent drivers (Claude Code, Cursor, custom orchestrators, CI) — every command emits parseable output and classifies its errors when the right env vars are set.

The CLI is for building agents, not invoking them in production. Production execution belongs in your application via the Python SDK (FruxonClient.execute / stream). The CLI's one execution surface is fruxon agents draft run, which runs the draft revision tagged Origin=TEST so it never mixes with production metrics or budgets.

Install

pip install fruxon

Verify:

fruxon --version
fruxon doctor       # diagnoses interpreter, SDK version, API reachability, auth

Requires Python 3.10+.

Sign in

fruxon login

This opens your dashboard, polls for completion, and stores the resulting token in your OS keychain (macOS Keychain, Linux Secret Service, Windows Credential Manager). The org and base URL go to ~/.fruxon/credentials as plain JSON.

The minted key's access level is declared with --preset (default developer — build, test, and run drafts without deploying live):

fruxon login --org acme-corp                          # browser flow, locked to an org
fruxon login --preset maintainer                      # request deploy rights
fruxon login --token fx_pat_... --org acme-corp        # non-interactive (CI)
fruxon login --no-browser                             # print the URL instead of opening it

Want to know which credential the CLI is actually using? fruxon whoami shows the active values and where each came from — flag, env var, keychain, file, or default. fruxon logout clears everything.

Drive it with your coding agent

The fastest way to build on Fruxon is to let an AI coding agent drive the CLI. The CLI is self-describing — it ships its own command tree (fruxon describe), playbooks (fruxon guides), and snippets (fruxon examples) — so the agent can look up exactly what each task needs.

To use it: install the package, run fruxon login, paste the prompt into Claude Code, Cursor, or any coding agent, and replace the last line with what you want to build. The agent discovers the rest.

You're my Fruxon build agent. The `fruxon` CLI is installed and I've run `fruxon login`. The CLI is self-describing — lean on it instead of guessing flags or field names.

Bootstrap once, before anything else:
1. `fruxon guides show fruxon-agent-mode` — the contract for driving the CLI as an agent: JSON-by-default output, NDJSON streams, typed exit codes (10–16), the `{"error":{…}}` stderr envelope, and interactive guards. Follow it.
2. `fruxon describe` — the entire command tree as one JSON document (every path, arg, option, default, and example). This is your reference: look up commands here instead of guessing, and re-read a path before you use unfamiliar flags.
3. Skim `fruxon guides list` and `fruxon examples` for procedural how-to and pasteable snippets when a task is unfamiliar.

For each task, work the discovery loop:
- **Learn the shape before writing a body.** `fruxon agents schema <agent>` for an agent's run parameters; `<write-command> --schema` (e.g. `fruxon agents revisions create <agent> --schema`) for a request-body JSON Schema. Build the payload to match — don't invent fields.
- **Pre-flight before submitting.** `fruxon agents validate <agent> -p k=v` checks run params client-side; `fruxon agents draft validate <agent> --online` lints the flow body and confirms its references resolve.
- **Iterate on the draft, never on production.** Pull → edit the local `.draft.json` → `fruxon agents draft run` (runs Origin=TEST, so it never touches prod metrics or budgets) → repeat. Mint a revision only once the draft is good.
- **Build order:** integration → tools on it → agent + revision referencing them → deploy → wire an inbound path (trigger or channel) → `fruxon agents check <agent>` to confirm it's actually runnable.
- **Debug from the record.** Every run prints a record id → `fruxon agents executions trace <agent> <id>`. Triage failures with `fruxon agents executions list <agent> --status FAILED`.

Hard rules:
- The CLI builds agents; it does not run deployed ones. Production invocation is the SDK's job (`FruxonClient.execute` / `stream`) — don't look for a `run` command.
- Secrets are never set through the CLI — credentials are entered by a human in the dashboard UI. Author integration/tool definitions that reference them; don't try to supply secret values.

My task: <describe what to build — e.g. "an agent that triages inbound support email and drafts a reply">

Discover the surface

Three offline, no-auth commands let any caller — human or AI agent — learn the CLI without grepping --help trees:

fruxon describe                       # entire CLI as one JSON document
fruxon examples [topic]               # curated runnable snippets by topic
fruxon completion {bash|zsh|fish}     # shell-completion script
  • describe is the single most useful call for an LLM driver: it returns every command path, args, options (long + short), types, defaults, choices, repeatable flags, and curated examples per top-level group. Versioned via schema_version so a driver can pin its parser.
  • examples is a hand-curated, offline catalog of pasteable invocations grouped by topic (agents, draft, integrations, executions, …). Renders aligned text for humans, JSON for agents.
  • completion prints the script for the named shell to stdout: eval "$(fruxon completion zsh)" to install.

For procedural how-to, the CLI ships its own playbooks:

fruxon guides list                       # the catalog
fruxon guides show fruxon-meet           # orientation
fruxon guides show fruxon-agent-mode     # the AI-agent driver contract
fruxon guides show fruxon-build-agent    # the draft → push → run → deploy loop
fruxon guides show fruxon-debug-revision # what to do when validation fails
fruxon guides show fruxon-use-integrations
fruxon guides show fruxon-create-integration

Load fruxon-agent-mode first if an AI agent is driving — it documents the JSON-output, NDJSON-stream, typed-exit-code, and structured-error contract end-to-end.

Browse agents

fruxon agents list                              # human-readable table
fruxon agents list --output json                # full payload, for scripting
fruxon agents list --output id                  # one ID per line, pipe-safe
fruxon agents list --include-disabled           # `-a` — include disabled agents
fruxon agents list --search invoice             # server-side substring match

In the table, the Rev column doubles as a deployability indicator: a yellow (none) means no revision is deployed yet, so the agent can't run until one is published.

Inspect a single agent:

fruxon agents get support-agent
fruxon agents get support-agent --output json

The schema → validate loop

Before constructing a payload — whether you'll send it via the SDK or run it against the draft — read the typed parameter shape and pre-flight your inputs. Each step is no-cost:

fruxon agents schema   my-agent                              # typed parameter metadata
fruxon agents validate my-agent -p user_query="hello"        # pre-flight your payload
fruxon agents validate my-agent --params ./params.json       # whole-object input
  • agents schema returns the full AgentParameters envelope: every parameter's name, type, required flag, single-select options, defaults, description. Add --revision N to inspect a specific revision.
  • agents validate runs the same checks the server applies (missing required, unknown parameter, wrong type, invalid single-select option) locally, surfacing every finding in one pass. Exits 12 on failure with a structured errors list — fix every problem at once, not one per round-trip. Same -p / --params / --stdin input model as agents draft run.

Server-side validation remains authoritative; the client-side checker just saves you the round-trip.

Author agents

A revision is immutable once created. The draft is the mutable working copy you iterate on — the same one an open studio tab edits. Build against the draft, then mint a revision from it.

The draft authoring loop

fruxon agents draft pull    my-agent                      # fetch to a local file
# edit my-agent.draft.json
fruxon agents draft push    my-agent                      # sync edits back
fruxon agents draft status  my-agent                      # local vs server sync state
fruxon agents draft run     my-agent -p k=v               # execute against the draft
fruxon agents draft validate my-agent --online            # lint the body; --online checks references resolve
fruxon agents draft evaluate my-agent --dataset <uuid>    # score against a golden dataset
fruxon agents draft undo    my-agent                      # server-side history
fruxon agents draft redo    my-agent
fruxon agents draft reset   my-agent                      # back to seed state
fruxon agents draft watch   my-agent                      # live-tail edits from other sessions
fruxon agents draft discard my-agent                      # delete server-side draft

draft run is the CLI's one execution surface and the "validate before you ship" verb. It runs the draft body without publishing, stamped Origin=TEST so it never mixes with production metrics or trips production budgets. With --file the local draft head is pushed first, so the edit-then-run cycle is one command; without it, the existing server-side draft runs as-is.

fruxon agents draft run my-agent -p query="hello"
fruxon agents draft run my-agent --file ./my-agent.draft.json -p query="hello"
fruxon agents draft run my-agent --no-stream -o json

Pass parameters

-p accepts four input forms (same model on draft run and validate):

# String value
fruxon agents draft run my-agent -p question="Hello" -p lang=en

# Typed JSON (number, bool, list, object)
fruxon agents draft run my-agent -p temperature:=0.7 -p tags:='["a","b"]'

# Read a value from a file
fruxon agents draft run my-agent -p prompt=@./prompt.md

# Whole-object input from a file or stdin
fruxon agents draft run my-agent --params ./params.json
cat params.json | fruxon agents draft run my-agent --stdin

# Multi-line value via $EDITOR (interactive only)
fruxon agents draft run my-agent --edit question

Output formats

fruxon agents draft run my-agent                  # stream text to your terminal
fruxon agents draft run my-agent --output json    # full execution envelope (implies --no-stream)
fruxon agents draft run my-agent --output table   # human-readable breakdown
fruxon agents draft run my-agent --no-stream      # wait for full response; show duration/cost
fruxon agents draft run my-agent --verbose        # expand tool args + results inline

Under agent mode, the default is NDJSON streaming on stdout — one JSON record per SSE event — without needing --output json.

Every successful run ends with a footer like:

56.8s  ·  $0.3265  ·  rev 7  ·  record 72c3c346-…
→ fruxon agents executions trace my-agent 72c3c346-…

The rev field is the base revision the draft ran against. The second line is copy-pasteable — jump straight to a post-mortem without retyping the IDs.

draft status

The source-of-truth for the iteration loop:

{
  "agent": "my-agent",
  "base_revision": 7,
  "local_version": 12,
  "server_version": 12,
  "local_edits": false,
  "needs_reconcile": false,
  "exists": true,
  "file": "my-agent.draft.json"
}

Boolean flags local_edits and needs_reconcile are designed for direct branching by an LLM driver ("if local_edits: push", "if needs_reconcile: pull").

draft evaluate

Scores the current draft against a golden dataset — runs the flow once per sample, then returns a quality score and deployment recommendation. Expensive (every sample costs real LLM tokens), so the prompt quotes the sample count first and --yes is required in non-interactive mode.

fruxon agents draft evaluate my-agent --list-datasets     # discover dataset ids
fruxon agents draft evaluate my-agent --dataset <uuid> --yes

The evaluation pins the draft snapshot at submit time, so further edits don't invalidate the verdict.

Mint and deploy revisions

fruxon agents create --file ./agent.json                  # new agent shell
fruxon agents revisions create my-agent --file ./rev.json # mint
fruxon agents revisions create my-agent --file ./rev.json --deploy   # mint + deploy
fruxon agents revisions get    my-agent 42                # fork from a known-good revision
fruxon agents revisions deploy my-agent 42                # make this revision live

revisions get prints the full revision body so you can fork from a known-good one — pipe it back through revisions create after edits.

Audit wiring before you rely on it

draft validate checks the flow body, but a working agent spans surfaces the body never declares. agents check audits whether a deployed agent is wired to run end-to-end:

fruxon agents check my-agent
fruxon agents check my-agent --revision 4
fruxon agents check my-agent -o json

It reports a doctor-style {overall, checks[]}: a deployed revision (hard fail if none), an inbound path (a bound trigger or channel so it can fire at all), a non-empty consult roster if any step enables consult, declared approver slots for every human-approval gate, and that references resolve. Exits non-zero only on a hard fail; advisory warn rows (a missing inbound path may be intentional for an SDK-invoked agent) stay exit 0 — branch on overall to gate CI on warnings too.

Inspect executions

Every run — production or test — lands here.

fruxon agents executions list  my-agent                         # recent executions
fruxon agents executions list  my-agent --status FAILED --limit 20
fruxon agents executions list  my-agent --origin TEST --since 2026-06-01
fruxon agents executions get   my-agent rec-abc123              # record summary (when/duration/cost/status)
fruxon agents executions trace my-agent rec-abc123              # step-by-step trace
fruxon agents executions trace my-agent rec-abc123 -o json | jq '.trace.steps[].kind'
fruxon agents executions result my-agent rec-abc123            # just the agent's output

For an LLM driver this is a two-step loop: list (filter --status FAILED to triage) to discover record IDs, then trace one by ID for the full step tree. The record ID is printed by agents draft run at the end of every execution.

Test history

Every agents draft run persists server-side, tagged Origin=TEST and owner-scoped. Browse and tail your saved test-chat sessions:

fruxon agents tests list   my-agent                       # recent test runs
fruxon agents tests show   my-agent <chat-id>             # full transcript
fruxon agents tests watch  my-agent                       # live tail (NDJSON in agent mode)
fruxon agents tests cost   my-agent [-r 12]               # cumulative dev spend
fruxon agents tests delete my-agent <chat-id> --yes

Per-origin budgets

Production and Test buckets are independent. A runaway dev loop can't trip the prod cap.

fruxon agents budget list   my-agent
fruxon agents budget get    my-agent --origin TEST
fruxon agents budget set    my-agent --amount 50 --origin TEST --threshold 80 --enforce
fruxon agents budget delete my-agent --origin TEST --yes

When --origin is omitted, commands default to PRODUCTION — the safe default for monitoring. --threshold sets an alert percentage; --enforce / --no-enforce controls whether the cap hard-stops runs.

Human approvals

Operate a step's human-in-the-loop approval gate — the pending decisions an agent is blocked on:

fruxon agents approvals list    my-agent --status pending
fruxon agents approvals get     my-agent <approval-id>
fruxon agents approvals respond my-agent <approval-id> --approve --text "looks good" --yes
fruxon agents approvals respond my-agent <approval-id> --reject --reason "needs edits" --yes
fruxon agents approvals cancel  my-agent <approval-id> --reason "stale" --yes

The agent network

Fruxon agents can consult one another and route to people. These groups manage that fabric.

Participants

A participant is a person, group, or agent the network can route to or consult.

fruxon participants list
fruxon participants get    <participant>
fruxon participants create --file ./participant.json
fruxon participants update <participant> --file ./participant.json
fruxon participants enable  <participant>
fruxon participants disable <participant>
fruxon participants delete  <participant> --yes
fruxon participants bind    <participant> <agent>          # add to an agent's consult roster
fruxon participants unbind  <participant> <agent> --yes
fruxon participants roster  <participant> <agent> --file ./policy.json   # set its consult policy

Capabilities & consult pins

A capability is the routing vocabulary the network consults on; a consult pin is a deterministic capability → participant override.

fruxon capabilities list
fruxon capabilities get    <capability>
fruxon capabilities create --file ./capability.json
fruxon capabilities update <capability> --file ./capability.json
fruxon capabilities delete <capability> --yes

fruxon consult-pins list [--agent <agent>]
fruxon consult-pins get    <pin>
fruxon consult-pins create --file ./pin.json
fruxon consult-pins delete <pin> --yes

Roster, inbox & topics

Read-only views into an agent's network state:

fruxon agents roster my-agent                          # who consults this agent + their policy
fruxon agents inbox  my-agent [--participant p_123]    # the agent's attention landscape (focal/home/suspended topics)
fruxon agents topics list   my-agent [--state open] [--participant p_123]
fruxon agents topics search my-agent --query "refund"  # semantic search over topics
fruxon agents topics get    my-agent <topic>
fruxon agents topics messages my-agent <topic>

Channels, endpoints

How an agent receives and sends inbound messages:

fruxon agents channels  list my-agent                  # channel bindings
fruxon agents endpoints my-agent                       # resolved messaging endpoints + bot identity

Memory

Inspect and prune what an agent remembers across conversations:

fruxon agents memory list           my-agent [--subject p_123] [--search "..."] [--scope ...]
fruxon agents memory subjects       my-agent              # subjects the agent holds memories about
fruxon agents memory get            my-agent <memory>
fruxon agents memory forget-subject my-agent <subject> --yes

Sandbox

agents sandbox drives a full agent-network simulation — turns from participants, trigger fires, consults, and approvals — without touching production. Useful for exercising multi-party flows before deploy.

fruxon agents sandbox open  my-agent                                  # → session id
fruxon agents sandbox turn  <session> --as p_123 --text "hi" --await  # send a turn as a participant
fruxon agents sandbox fire  <session> --trigger <id> --sample-payload @evt.json --await
fruxon agents sandbox resolve-input <session> --trigger <id>          # preview the mapped params
fruxon agents sandbox answer <session> <operation-id> --text "approved" --yes
fruxon agents sandbox stream <session>                                # tail the session
fruxon agents sandbox close  <session>
fruxon agents sandbox test   ./scenario.test.yaml                     # run a scenario file (--junit for CI)

sandbox test runs a declarative *.test.{yaml,json} scenario — setup, turns, and expect assertions (including semantic reply_judge grading) — and can emit JUnit XML for CI.

Manage integrations

An integration is a connection to an external service — an HTTP API, a SaaS product, an MCP server. It's the container tools live under, and the first rung of building an agent: connect an integration → define tools on it → reference those tools from the agent's flow.

fruxon integrations list [--search X] [--type T] [--tag T] [--has-configs] [--has-triggers] [--has-channels]
fruxon integrations get    <id>
fruxon integrations create  --file <int.json>
fruxon integrations update <id> --file <int.json>
fruxon integrations verify <id> --file <auth.json>
fruxon integrations open   <id>                          # dashboard page in default browser

list / get take plain flags. create / update take a --file JSON body (CreateIntegration / UpdateIntegration) that defines the integration's shape and auth metadata; - reads stdin. Credential values aren't part of this body — they're entered by a human in the dashboard (see Integration configs below).

verify checks that an auth config actually connects: --file is a VerifyAuthConfigRequest. A failed check is a normal result — the detail is printed and the exit code is 12 (validation), so it works as a pre-flight gate.

Connect via OAuth

OAuth needs a browser consent step no headless client can complete. integrations authorize mints the provider authorization URL so a human can click it; the connection is then saved as a tenant config every referencing agent shares.

fruxon integrations authorize google_sheets
fruxon integrations authorize outlook --scope Mail.Read --scope offline_access
fruxon integrations authorize salesforce --config-param instanceUrl=https://acme.my.salesforce.com

Auto-detects the integration's application-level OAuth2 method; pass --auth-method <id> if it declares more than one.

Discover event types

fruxon integrations triggers gmail        # event types this integration can fire an agent on
fruxon integrations triggers slack --output json

Each row's id is the eventType a triggers create body listens for (e.g. slack.message.received, github.pull_request.opened); its payloadFields are the dotted paths a binding's parameterMappings (kind PAYLOAD_PATH) can read. This is how you wire an inbound-event trigger without guessing the event id or payload paths.

Integration configs

A config is one filled-in instance of an integration — an auth credential plus any connection params. The shape is authored via integrations create; the values are entered through the dashboard (the CLI never accepts secrets).

fruxon integrations configs list <id>     # tenant-level configs registered for this integration
fruxon integrations configs get  <id> <config-id>

MCP servers

Each integration can be exposed as an MCP server so Claude Desktop, Cursor, and other MCP-capable clients can call its tools directly.

fruxon integrations mcp status <id>
fruxon integrations mcp enable <id> --config <config-id>

enable mints a dedicated mcp:invoke-scoped key bound to this MCP only and prints the secret exactly once — store it where your MCP client reads its config. Disabling and key rotation happen in the dashboard.

Manage tools

A tool is a single callable capability an agent can invoke. Tools are integration-scoped — every command takes the integration as its first positional argument.

fruxon tools list   <integration> [--type T]
fruxon tools get    <integration> <tool>
fruxon tools create <integration> --file <tool.json>
fruxon tools update <integration> <tool> --file <tool.json> [--python]
fruxon tools delete <integration> <tool>
fruxon tools test   <integration> --file <tool-test.json> [-p k=v]

Write commands take a --file JSON body (CreateToolRequest / Tool / ToolTestRequest) carrying the structured descriptor + parametersMetadata. update --python routes Python-script tools through their separate backend endpoint; update is a wholesale replace, not a patch. test runs the tool with sample parameters before you wire it into an agent — -p key=value overlays runtime params onto the file's, and the tool's response goes to stdout (pipe-safe).

The CLI auto-fills integrationId in the body from the positional argument on both create and update, so you can omit it. If you do include it and it doesn't match, the CLI rejects loudly rather than letting the server 400 with a less helpful message.

Placeholders in tool definitions. Tool URLs, headers, query params, and bodies template via double curly braces — {{name}} (not {name}, which is passed through literally and silently breaks at runtime). Names are flat — no auth. / config. / param. prefix. All sources (tool call parameters, the integration config's non-secret parameters, and built-ins like {{tenant}}) merge into one namespace.

Don't write the Authorization header in your tool. The auth provider injects it automatically based on the integration's authMetadata.type (BEARER_TOKEN → Authorization: Bearer <token>, API_KEY → whichever header is configured). Need a non-standard scheme like Discord's Bot or G2's Token token=? Set authSettings: { Scheme: "Bot", ValuePrefix: "" } on the authMetadata — still no template needed in the tool itself.

Triggers

A trigger is a scheduled or event source that fires an agent. Discover, author, and bind them:

fruxon triggers list
fruxon triggers get    <trigger>
fruxon triggers create --file ./trigger.json
fruxon triggers update <trigger> --file ./trigger.json
fruxon triggers delete <trigger> --yes
fruxon triggers fire   <trigger> --file ./payload.json --yes   # simulate firing
fruxon triggers bind   <trigger> <agent>                       # wire it to an agent
fruxon triggers unbind <trigger> <agent> --yes

A bound trigger is what gives an agent an inbound path — without one (or a channel binding) the agent only runs via test / the SDK. Use integrations triggers to discover the eventType and payload paths a trigger body listens for, and agents check to confirm the wiring is complete.

Knowledge assets (RAG)

An asset is a document an agent step can query. Upload, vectorize, and inspect ingestion:

fruxon assets list
fruxon assets get    <asset>
fruxon assets create --file ./handbook.pdf --vectorize          # upload + ingest
fruxon assets create --file ./handbook.pdf --vectorize --embedding-model <m> --embedding-provider <p>
fruxon assets wait   <asset>                                     # block until ingestion is queryable
fruxon assets operations <asset>                                 # ingestion / re-index operations
fruxon assets delete <asset> --yes
fruxon assets embedding-models                                   # models available for vectorization
fruxon assets supported-types                                    # file types you can upload

Object storage

Upload local files (e.g. images for OCR / vision steps) and get back a link you can drop into an agent input:

fruxon storage upload --file ./invoice.png                       # → fileId + promptLink
fruxon storage upload -f ./invoice.png -o link                   # just the prompt link (image:fileId form)
fruxon storage download <file-id> --out ./local.png
LINK=$(fruxon storage upload -f ./invoice.png -o link)
fruxon agents draft run recipe_ocr -p image="$LINK"

upload requires the assets:write scope; --temporary marks the file for short-lived use.

Secrets

Discover tenant secrets a flow step can reference — metadata only, never values:

fruxon secrets list
fruxon secrets get    <secret>
fruxon secrets grants <secret>     # which agents/steps are granted this secret

Evaluation metrics

Browse the tenant evaluation-metric catalog — the ids LLM-judge steps and eval runs reference:

fruxon metrics list
fruxon metrics list --include-deprecated

LLM providers

Read-only inspection of the LLM providers (OpenAI, Anthropic, Google, …), their models, and your saved configs:

fruxon llm-providers list                       # providers + status
fruxon llm-providers get    <provider-id>       # metadata, config schema, models
fruxon llm-providers models <provider-id>
fruxon llm-providers configs list <provider-id> # tenant-saved configs for this provider
fruxon llm-providers configs get  <provider-id> <config-id>

Product skills

Skills are Fruxon's procedural knowledge — playbooks an agent can load before tackling a task. fruxon skills is the read-only surface for the product skill catalog (different from fruxon guides, which are local CLI playbooks).

fruxon skills list                                # every skill visible to your org
fruxon skills show fruxon-create-integration      # full procedural content to stdout

show outputs raw markdown — pipe it into glow for a rendered view, or into a file to read alongside other docs.

Manage tokens

fruxon keys covers the read-and-revoke half of token management. Minting and rotation deliberately happen in the dashboard, not the CLI — fruxon keys mint opens the browser so the secret is only revealed to a human-authenticated session, never to an LLM agent or CI logger reading the terminal.

For the scope vocabulary, presets (Observer / Operator / Developer / Maintainer / Admin), audit history, MCP auto-mint, and inbound:deliver semantics, see the Tokens guide.

fruxon keys mint                  # open the dashboard's tokens page in your browser
fruxon keys list                  # all keys in your org (prefix-only)
fruxon keys revoke <id>           # flip inactive (reversible from dashboard)
fruxon keys delete <id> --yes     # hard delete (irreversible) — --yes required in agent mode
fruxon keys history <id>          # audit timeline
fruxon keys scopes                # every scope the server mints against

Why minting isn't a CLI command. When an LLM agent runs the CLI (Claude Code, Cursor, Aider, etc.), its stdout enters the agent's context window — durably part of the conversation, often persisted on the AI provider's backend. A keys create that prints fx_pat_<secret> would leak the value into that pipeline every time. The browser handoff is the only channel where "the secret reaches the user without traversing the agent" is structurally guaranteed.

Inside the dashboard you pick a scope preset (observer / operator / developer / maintainer / admin) and copy the secret into your password manager or CI secrets store. Hand the agent the prefix (fx_pat_aB3z) so it can identify the key for revoke / history calls — never the full secret.

CI workflows should pre-mint a key in the dashboard once and store the secret in their secrets manager (GITHUB_SECRETS, etc.), not call out to keys mint at runtime. Runtime self-minting is harder to audit and rarely what you actually want.

Generate request schemas (--schema)

Every write command that takes --file <body.json> also accepts --schema. It pulls the live OpenAPI spec from the server you're talking to and prints the JSON Schema for the request body — $ref closure included, allOf inheritance flattened — as a single self-contained document on stdout.

This is the agent-native equivalent of Postman's "see the request shape" affordance: pipe the schema into your LLM context, generate a valid body, and submit it.

fruxon agents create --schema > create-agent.schema.json
fruxon agents revisions create my-agent --schema > revision.schema.json
fruxon integrations create --schema > integration.schema.json
fruxon tools create <integration> --schema
fruxon triggers create --schema
fruxon participants create --schema
fruxon capabilities create --schema
fruxon consult-pins create --schema

Properties:

  • Live, not bundled — fetched from /swagger/v1/swagger.json on the configured --base-url, so the schema always matches the server's contract.
  • No auth required — the OpenAPI spec is public; --schema short-circuits before credentials are touched.
  • Self-contained — $refs rebased to #/$defs/…, polymorphic allOf collapsed into discriminated variants with const-pinned discriminator values, so strict validators (jsonschema.validate) accept exactly what the server does.

--schema (request body) vs agents schema (run parameters). The two are different surfaces. --schema on a write command gives you the JSON Schema for the request body you'd submit to that endpoint (e.g. CreateAgentRevision). fruxon agents schema <id> gives you the typed metadata for the parameters a deployed agent's run accepts.

Diagnose your setup

fruxon doctor                  # full check
fruxon doctor --offline        # skip network probes
fruxon doctor --output json    # machine-readable, for CI
fruxon doctor --verbose        # show per-check detail

Doctor walks through interpreter version, SDK version (with "newer release available" check), credentials, API reachability, and an authenticated probe. Exit code is 0 on green, 12 on any warning or failure — useful as a CI precheck.

Manage configuration

Non-secrets live in ~/.fruxon/credentials; the token lives in your OS keychain.

fruxon config list                                # show everything, token redacted
fruxon config get org                             # raw value to stdout — usable in $(...)
fruxon config set org=acme base_url=https://staging.fruxon.com
fruxon config unset base_url                      # clear a single field
fruxon logout                                     # clear everything

Credentials & precedence

The CLI resolves auth in this order — first non-empty wins:

  1. Explicit flags — --token / --org / --base-url.
  2. Environment variables — FRUXON_TOKEN / FRUXON_ORG / FRUXON_BASE_URL.
  3. Stored credentials (managed by fruxon login).

The stored layer is split for safety:

FieldStorage
tokenOS keychain (macOS Keychain, Linux Secret Service, Windows Credential Manager). Falls back to the JSON file with 0600 perms when the keyring is unavailable.
org, base_url~/.fruxon/credentials (plain JSON).

Set FRUXON_NO_KEYRING=1 to force the JSON-file fallback.

Environment variables

VarEffect
FRUXON_TOKENDefault token.
FRUXON_ORGDefault organization.
FRUXON_BASE_URLOverride the API base URL (staging / self-hosted).
FRUXON_CONFIG_DIROverride the credentials directory (default ~/.fruxon).
FRUXON_AGENT_MODE=1Opt into the agent-mode contract (JSON outputs, NDJSON streams, typed exits, structured errors). Also auto-detected from CLAUDECODE=1 / CI=1.
FRUXON_NO_KEYRING=1Force the JSON-file fallback for the token.
FRUXON_CA_BUNDLEPath to a PEM file of extra trusted CAs (corporate TLS proxies).
FRUXON_INSECURE=1Disable TLS verification (dev/staging only — never production).
FRUXON_NO_BANNER=1Suppress all branding chrome.
FRUXON_NO_UPDATE_CHECK=1Opt out of the "newer version available" notifier.
NO_COLOR=1Standard convention — disables color output.

Agent mode

When CLAUDECODE=1, CI=1, or FRUXON_AGENT_MODE=1 is set, the CLI flips to a contract designed for parseability. Full reference: fruxon guides show fruxon-agent-mode.

JSON by default

Every --output flag defaults to json. Every read command emits a stable shape; every write echoes the server's response so a driver doesn't need a follow-up GET. Bare fruxon emits a one-line JSON manifest with next-step commands.

NDJSON streaming

fruxon agents draft run and fruxon agents tests watch re-emit their SSE streams as newline-delimited JSON on stdout — one record per line, readline() + json.loads consumable, schema_version-pinned. Example frame for a draft run:

{"type":"start","schema_version":2,"agent":"my-agent"}
{"type":"text","delta":"Hel"}
{"type":"text","delta":"lo."}
{"type":"tool_call","id":"tc-1","name":"search","arguments":{"q":"x"}}
{"type":"tool_result","id":"tc-1","status":"succeeded","result":{"hits":3}}
{"type":"usage","input_tokens":100,"output_tokens":250}
{"type":"done","agent":"my-agent","record_id":"rec-99","duration_ms":1234,"total_cost":0.0012}

Additional frame types: step_trace, status, error, and a {"type":"done","status":"waiting_for_human",…} variant when a run blocks on a human-approval gate.

Typed exit codes

Every failure classifies into one of these:

CodeSlugMeaning
0—Success
10auth_required401/403, no credentials, missing scope
11not_found404 — agent / integration / tool doesn't exist
12validationBad flag, malformed body, pre-flight failed
13conflict409 — draft moved, version mismatch
14server_error5xx, mid-stream server failure
15network_errorCouldn't reach the API
16interactive_requiredA blocking prompt was hit

A driver's retry/abort logic should match on these numbers, not on prose.

Structured error envelope

In agent mode, every failure emits a single JSON line on stderr (stdout stays reserved for the command's primary output):

{"error":{"code":"auth_required","message":"No org found.","exit_code":10,"hint":"Run fruxon login --org <id>..."}}

To recover, read the last JSON line on stderr after a non-zero exit.

Interactive guards

Any path that would block on stdin fails fast with exit 16 (interactive_required) and a hint naming the bypass flag:

PathBypass
fruxon login (no --token)Pass --token $FRUXON_TOKEN
fruxon agents draft run --editPass -p key=value or --params file.json
fruxon agents draft evaluate (no --yes)Pass --yes — it costs real money
Any destructive verb (keys delete, assets delete, triggers delete, agents tests delete, agents budget delete, agents memory forget-subject, participants delete, …)Pass --yes

Shell completion

# Install for your shell — one-liner via eval, or pipe to a completions dir
eval "$(fruxon completion zsh)"

# Persistent install
fruxon completion bash > /etc/bash_completion.d/fruxon
fruxon completion fish > ~/.config/fish/completions/fruxon.fish

Hosting & Data Residency

Where Fruxon runs, where your data lives, and the deployment models available for regulated and enterprise teams

Python SDK

Execute Fruxon agents programmatically from Python — one-shot, streaming, multi-turn — plus full authoring, agent-network, and observability APIs.

On this page

Install
Sign in
Drive it with your coding agent
Discover the surface
Browse agents
The schema → validate loop
Author agents
The draft authoring loop
Pass parameters
Output formats
Run footer
draft status
draft evaluate
Mint and deploy revisions
Audit wiring before you rely on it
Inspect executions
Test history
Per-origin budgets
Human approvals
The agent network
Participants
Capabilities & consult pins
Roster, inbox & topics
Channels, endpoints
Memory
Sandbox
Manage integrations
Connect via OAuth
Discover event types
Integration configs
MCP servers
Manage tools
Triggers
Knowledge assets (RAG)
Object storage
Secrets
Evaluation metrics
LLM providers
Product skills
Manage tokens
Generate request schemas (--schema)
Diagnose your setup
Manage configuration
Credentials & precedence
Environment variables
Agent mode
JSON by default
NDJSON streaming
Typed exit codes
Structured error envelope
Interactive guards
Shell completion
Links