# A command-line entry point

> Gives your app a command a script or a grader can call: a function that takes one case and returns one result, run with `osy run Exam --arg-file c=case.json --output json`. Stdout carries the result as JSON and nothing else; a failure is JSON on stderr with a stable code and a non-zero exit.

<!-- id: local-command-line-entry-point · area: local · stability: stable · html: https://osysharp.com/reference/local/command-line-entry-point/ -->

## Summary        {#summary}

When a brief asks for an **exam CLI**, a command that takes a JSON test case, or a way to check the app before its
screens exist, you don't need a script. Write one function that takes the case and returns the result, and the
command is `osy run`:

```console
osy run Exam --arg-file c=case.json --output json
```

It prints the function's result as JSON on stdout, and nothing else goes there. A failure prints a JSON error on
stderr and exits non-zero. If the project was never compiled, or has changed since it last was, `osy run` compiles
it first.

## Signature      {#signature}

```console
osy run <function> [path] [--args-file <path|->] [--args-stdin] [--arg-file NAME=<path|->] [--arg NAME=VALUE]
                   [--output json] [--no-compile] [--as <login> --password <pw>]
```

## Description    {#description}

### What does the function look like?   {#the-function}

Write a function that takes one case object and returns one result object. Model both as classes, so each field has
a name and a type. The function is ordinary Osy#: your tests call it, and so can a page.

```osy title="one case in, one result out" test app=local-command-line-entry-point
class ExamCase {
  public string Question = "";
  public List<int> Numbers = [];
}

class ExamResult {
  public int Total;
  public string Verdict = "";
}

ExamResult Exam(ExamCase c) {
  var total = 0;
  foreach (var n in c.Numbers) { total = total + n; }
  return new ExamResult { Total = total, Verdict = total > 10 ? "big" : "small" };
}
```

A grader's case file is the case itself:

```json
{ "question": "add them up", "numbers": [4, 5, 6] }
```

Field names match without regard to case, so `numbers` binds `Numbers`.

### How does the case get in?   {#input}

There are two shapes. Pick the one that fits the file you are given.

| the file holds | flag | binds |
|---|---|---|
| **one value**, such as a test case | `--arg-file c=case.json` | the whole document to the parameter `c` |
| **every argument**, one property per parameter | `--args-file args.json` | each property to the parameter it names, like `--args-json` |

Use `-` in place of a path to read standard input. `--args-stdin` means `--args-file -`.

```console
osy run Exam --arg-file c=case.json --output json      # the case, from a file
osy run Exam --arg-file c=- --output json < case.json  # the case, piped in
osy run Exam --args-file args.json --output json       # args.json is {"c": {…}}
cat args.json | osy run Exam --args-stdin --output json
```

You can layer them. One whole-arguments source (`--args-json`, `--args-file` or `--args-stdin`) goes first, each
`--arg-file` goes on top of it, and each `--arg` goes on top of those. Standard input can only be read once, so if two
flags ask for it, `osy run` refuses. It also refuses, rather than waiting, when a flag asks for standard input and
nothing is piped in.

### What comes out?   {#output}

With `--output json`, the result is printed on stdout as **one line of JSON** and the exit code is `0`:

```console
$ osy run Exam --arg-file c=case.json --output json
{"total":15,"verdict":"big"}
```

A number comes out as `42`, a string as `"hola"`, a list as `[…]`, and a returned row as its fields with its `id`. A
function that returns nothing prints `null`. Nothing else goes to stdout: the platform starting, a compile on demand,
and any notes are all written to stderr. A script can read stdout with a single JSON parse.

`--json` is different. It prints the whole answer (`success`, `output`, `result`, `error`, `code` and `ranAs`) as one
document. Use one flag or the other, not both.

### What does a failure look like?   {#codes}

When the function throws or is refused, stdout stays empty, stderr gets one line of JSON, and the exit code is not
zero:

```console
$ osy run Exam --arg-file c=case.json --output json
{"error":{"code":"denied","message":"You do not have permission to create a note. — …"}}
$ echo $?
1
```

Branch on `code`. The message is written for a person and may change. The codes are stable:

| code | means | what to do |
|---|---|---|
| `invalid` | the function refused the input (a validation error, a `throw` of a validation kind) | the case is wrong, or the rule is |
| `denied` | the app's security refused the caller (a rule, a policy, `[Authorize]`) | run as someone allowed: `--as <login> --password <pw>` |
| `not-found` | something the function looked up is not there | check the ids in the case |
| `conflict` | the change clashes with the data as it is | re-read and retry |
| `unavailable` | a service the function called did not answer | try again later |
| `too-many-attempts` | sign-in attempts are being limited | wait, then try again |
| `fault` | the function failed in a way it did not declare (a bug, or a plain `throw`) | read the message, fix the function |
| `function-not-found` | no function has that name | check the spelling; the message lists what can run |
| `function-not-runnable` | the name is a method, a test, a constructor or a workflow step | call a top-level function |
| `function-ambiguous` | two kits declare that name | name it in full |
| `sign-in-refused` | `--as` did not sign in | check the login, password and `--code` |
| `bad-arguments` | the flags or a case file could not be read (missing file, not JSON, nothing piped) | the message names the flag |
| `compile-failed` | the compile on demand found errors (they are on stderr above the error line) | fix them |
| `not-a-project` | there is no `app.osy` here | run it in the project's folder, or pass its path |
| `platform-unavailable` | the local platform could not be started | the message says why |
| `platform-unreachable` | the local platform stopped answering (exit code `2`) | start it again: `osy launch` |

### Does it need compiling first?   {#compile-on-demand}

No. `osy run` compiles the project first if the local platform has never compiled it, or if the source has changed
since it last did. It says so on stderr:

```console
$ osy run Exam --arg-file c=case.json --output json
The source changed since the last compile — compiling it first (`osy compile`).
{"total":15,"verdict":"big"}
```

`osy seed <name>` does the same, so on a fresh clone `osy seed ExamWorld` followed by `osy run Exam …` works with no
other step. `--no-compile` runs whatever the platform has now.

### Prove it with a test as well   {#test-it}

The command is for the grader. Your own check is a test that calls the same function, which `osy check` runs with
everything else:

```osy title="the exam's own test" test app=local-command-line-entry-point
[Test]
void a_case_adds_its_numbers() {
  var result = Exam(new ExamCase { Question = "add them up", Numbers = [4, 5, 6] });
  Assert.Equal(15, result.Total);
  Assert.Equal("big", result.Verdict);
}
```

If the brief says to pass the exam cases before building screens, build this function and its command first, and run
the command on a real case before you start on any page.

## See also       {#see-also}

[Running a function](https://osysharp.com/reference/local/running-a-function/) — `osy run` in full: who it runs as, entity arguments, `--json`.

[Compiling your app](https://osysharp.com/reference/local/compiling-your-app/) — what the compile on demand runs.

[[Test] / [TestFixture]](https://osysharp.com/reference/testing/test/) — writing the test that calls the same function.
