CLI

The fruxon command ships with the Python SDK (pip install fruxon) and turns Fruxon into a terminal-first workflow: sign in once, list agents, run them, chat with them, and inspect any past execution.

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 API key in your OS keychain (macOS Keychain, Linux Secret Service, Windows Credential Manager). The org and base URL go to ~/.fruxon/credentials as plain JSON.

Non-interactive sign-in (e.g. CI):

fruxon login --api-key fxn_... --org acme-corp

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 --all             # include disabled agents

In the table, the Rev column doubles as a runnability indicator: a yellow (none) means no revision is deployed yet, so fruxon run will fail until one is published.

Inspect a single agent:

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

When the agent has a deployed revision, the output ends with a copy-pasteable fruxon run line including the right -p flags.

Author and deploy agents

agents create makes a new agent shell from a JSON definition; agents revisions author and deploy the flow that runs inside it.

fruxon agents create --file ./agent.json                # new agent shell
fruxon agents revisions create my-agent --file ./rev.json
fruxon agents revisions get my-agent 42                 # seed for the next revision
fruxon agents revisions deploy my-agent 42              # makes `fruxon run` use it

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

Test a draft flow

fruxon agents test runs a draft flow definition against an existing agent — without publishing it. The "validate before you ship" loop.

fruxon agents test my-agent --file ./agent.json -p query="hello"
fruxon agents test my-agent --file ./agent.json --no-stream -o json
cat agent.json | fruxon agents test my-agent --file -

--file is an AgentTestRequest JSON body — the candidate flow plus its subAgents, assets, integrationConfigs, llmConfigs, and baseRevision. The my-agent argument scopes the run to an existing agent: it gates Editor access and resolves any masked secrets from the base revision's stored configs.

The result is identical in shape to fruxon run — same streaming view, --output formats, and duration/cost/record footer — because :test returns the same envelope as :execute. Exit code is 0 on success, non-zero on failure, so keeping the definition file in your repo turns this into a CI gate for agent changes. Requires Editor access to the agent.

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]
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 — the CreateIntegration / UpdateIntegration payload (id, displayName, configMetadata); - reads stdin. On update, omit credential fields to keep existing values (the API never returns secrets).

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 1, so it works as a pre-flight gate.

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.

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.

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 agents test my-agent --schema > test-request.schema.json
fruxon integrations create --schema > integration.schema.json
fruxon integrations update <id> --schema
fruxon integrations verify <id> --schema
fruxon tools create <integration> --schema
fruxon tools update <integration> <tool> --schema
fruxon tools test <integration> --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. Switch base URLs and you get that server's shape.
• 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.

Typical LLM-driven flow:

fruxon tools create github --schema > schema.json
# feed schema.json + your intent to your coding agent, get back tool.json
fruxon tools create github --file ./tool.json

Drop into your coding agent

Paste this into Claude Code, Cursor, or any coding agent to bootstrap a Fruxon build session. The agent uses --schema to discover the exact request shape from the live OpenAPI spec — no guessing field names, no stale examples.

You're building on Fruxon. The `fruxon` CLI is installed and I've already run `fruxon login`.

Operating rules:

1. **Discover shape before writing JSON.** Every write command accepts `--schema` and prints the live JSON Schema for its `--file` body. Always run `--schema` before authoring a body, never invent field names.
2. **Use `--file` for writes, `-o json` for reads.** All write commands take `--file body.json` (or `--file -` for stdin). All read commands accept `-o json` for machine-parseable output.
3. **Build order:** integration → tools on it → agent + revision that references them → deploy → run.
4. **Validate before deploy.** Use `fruxon agents test <id> --file ./rev.json` to dry-run a draft revision against an existing agent; only `fruxon agents revisions create` + `... deploy` once it passes.
5. **Never put secrets in files you commit.** Credential fields stay in the dashboard or are submitted ephemerally. On `integrations update`, omit credential fields to keep existing values.

Reference loop you'll use repeatedly:

```bash
fruxon <resource> <verb> --schema > schema.json   # live request shape
# author body.json from schema.json + the user's intent
fruxon <resource> <verb> --file ./body.json       # submit
```

Useful commands:

```bash
fruxon agents list -o json
fruxon integrations list -o json
fruxon tools list <integration> -o json
fruxon agents get <id> -o json                    # full revision body — fork from a known-good one
fruxon agents test <id> --file ./rev.json         # validate draft without deploying
fruxon agents revisions create <id> --file ./rev.json
fruxon agents revisions deploy <id> <n>
fruxon run <id> -p key=value                      # execute
fruxon trace <id> <record-id>                     # post-mortem
fruxon doctor                                     # diagnose setup
```

Now: <describe what to build>

Run an agent

One-shot execution. Streams the response by default.

fruxon run my-agent

Pass parameters

-p accepts four input forms:

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

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

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

# Whole-object input from a file
fruxon run my-agent --params ./params.json

# Whole-object input from stdin
cat params.json | fruxon run my-agent --stdin

# Multi-line prompt via $EDITOR
fruxon run my-agent -e question

Output formats

fruxon run my-agent                  # stream text to your terminal
fruxon run my-agent --output json    # full execution envelope (implies --no-stream)
fruxon run my-agent --output table   # human-readable breakdown
fruxon run my-agent --no-stream      # wait for full response; show duration/cost

Pin a specific revision

fruxon run my-agent --revision 42

Run footer

Every run ends with a footer like:

56.8s  ·  $0.3265  ·  record 72c3c346-…
→ fruxon trace my-agent 72c3c346-…

The second line is copy-pasteable — jump straight to a post-mortem without retyping the IDs.

Interactive REPL

For multi-turn conversation with session continuity:

fruxon chat my-agent

Each turn streams, and the session ID is threaded into the next turn automatically so the agent remembers context.

fruxon chat my-agent --input-key question     # if the agent's param isn't `prompt`
fruxon chat my-agent -p lang=en               # static params sent on every turn
fruxon chat my-agent --session sess-abc       # resume an existing session

Slash commands inside the REPL:

Manage API keys

fruxon keys covers the read-and-revoke half of key 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 (Runner / Builder / Read-only / Admin), audit history, MCP auto-mint, and inbound:deliver semantics, see the API Keys guide.

fruxon keys mint                  # open the dashboard's API-keys 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>           # hard delete (irreversible)
fruxon keys history <id>          # audit timeline
fruxon keys scopes                # every scope the server mints against

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.

Browse skills

Skills are Fruxon's procedural knowledge — playbooks an agent can load before tackling a task. fruxon skills is the read-only surface for browsing the catalog from your terminal.

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.

Browse LLM providers

Read-only inspection of the LLM providers (OpenAI, Anthropic, Google, …) and models wired to your tenant.

fruxon llm-providers list                # providers + status
fruxon llm-providers get <provider-id>   # full payload: metadata, config schema, models
fruxon llm-providers models <provider-id>

Inspect a past execution

fruxon trace my-agent rec-abc123                    # record summary + step-by-step trace
fruxon trace my-agent rec-abc123 --summary-only     # just the summary
fruxon trace my-agent rec-abc123 --json | jq .trace # machine-readable

The record ID is printed by fruxon run at the end of every execution.

Diagnose your setup

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

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, 1 on any warning or failure — useful as a CI precheck.

Manage configuration

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

fruxon config list                                # show everything, api_key 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 — --api-key / --org / --base-url.
2. Environment variables — FRUXON_API_KEY / FRUXON_ORG / FRUXON_BASE_URL.
3. Stored credentials (managed by fruxon login).

The stored layer is split for safety:

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

Environment variables

Agent mode

When CLAUDECODE=1, CI=1, or FRUXON_AGENT_MODE=1 is set, the CLI:

• Defaults --output to json for run, agents list/get/test, integrations list/get, tools list/get, doctor.
• Suppresses banners and color chrome.
• On bare fruxon invocation, emits a one-line JSON manifest describing auth state + next-step commands.

This makes the CLI ergonomic for LLM agents and CI pipelines without extra flags. Explicit --output X always wins.

Shell completion

fruxon --install-completion          # bash, zsh, fish, PowerShell

Links

• Python SDK guide — same package, programmatic surface.
• PyPI package