Discovering & running commands

Most of fore's commands are generated from the backend's OpenAPI spec, so the most reliable way to work with it is to let --help tell you what exists rather than guessing command or flag names.

Discover with --help

fore --help                              # top-level groups + static commands
fore organizations --help                # commands in the "organizations" group
fore test-case post-test-case --help     # arguments and flags for one command
fore schemas list                        # browse the data models
fore schemas show TestCase               # inspect one model's fields

How commands are named and grouped

The generator turns each backend operation into a command using a few consistent rules:

• Groups come from the operation's OpenAPI tags, slugified to kebab-case — e.g. fore organizations …, fore test-case …. Operations with no tag land in a catch-all untagged group.
• Command names are derived from the backend route, with the HTTP method prepended so the verb is always visible — e.g. get-users, post-test-case, delete-test-suite.
• Name collisions inside a group get a numeric suffix (-2, -3, …).

If a command you expect is missing, the backend route may not be tagged, or your spec cache may be stale — run fore refresh.

Passing arguments

Each generated command maps the endpoint's inputs onto the command line:

• Path parameters become required positional arguments (for example, an organization ID).
• Query parameters and top-level request-body fields become typed --flags. Required ones are marked [required] in --help.
• Nested objects or arrays in the body are exposed as --flags that take a JSON string.

For complex bodies, two escape hatches let you send the request body wholesale — these override any individual --field flags:

--json-body '<JSON>'    # inline JSON
--json-file <path>      # read the body from a file

Examples

# Inspect first, then call:
fore organizations get-users --help
fore organizations get-users 4b1f0c3e-...      # path param = org ID

# Create a test case with simple fields:
fore test-case post-test-case \
    --name "checkout flow" \
    --description "validates the checkout flow" \
    --test-suite-id 4b1f0c3e-...

# Use the escape hatch for a complex body:
fore test-case post-test-case --json-file ./new-test-case.json

Reading the output

• JSON responses are pretty-printed to stdout — pipe them to jq, grep, etc.

• Errors and status notifications go to stderr, including HTTP error details (status line + response body), after which fore exits with a non-zero code.

• Binary responses (such as screenshot endpoints) are streamed raw to stdout — redirect them to a file:

  fore <group> get-image <ID> > out.png

When scripting, capture stdout separately from stderr — only stdout carries the JSON payload:

fore organizations get-organizations | jq '.[].name'

Keeping the command tree current

The OpenAPI spec is cached under ~/.foreai/ and refreshes automatically once an hour. After a backend deploy you can pull the latest spec immediately:

fore refresh    # re-fetch the spec and report the operation count

If the network is unavailable but a cached spec exists, fore uses the stale cache so it keeps working offline.

Known limitations

Because commands are generated from the spec, a few endpoint shapes aren't specially handled:

• File-upload (multipart) endpoints expose their body fields like any other command. If the flag form doesn't fit, use --json-file.
• Streaming / server-sent-event endpoints block until the full response arrives.
• Header parameters are not exposed as flags.

Command names are derived from the backend route, so if a route is renamed on the backend, the corresponding fore command name changes with it — run fore refresh and re-check --help if a command seems to have moved.