[cli] Update docs

Author: paolino

cli/README.md

@@ -57,7 +57,14 @@ nix build .#macos64.tarball
 
 ```bash
 source <(anti --bash-completion-script "$(which anti)")
-antij(){ anti "$@" | jq .result; }
+antij() {
+    result=$(anti "$@")
+    if [ "$(echo "$result" | jq '.error')" != "null" ]; then
+        echo "$result" | jq 
+    else
+        echo "$result" | jq '.result'
+    fi
+}
 complete -o filenames -F _opt_env_conf_completion_anti antij
 ```
 

cli/docs/oracle-role.md

@@ -42,23 +42,6 @@ antij token | jq .state
 
 Critically the owner matches the wallet owner.
 
-## Publishing the oracle configuration
-
-Before requesters can request test-runs, the oracle should select the agent identity and in general expose validation parameters so that the requesters and the agent can pre-validate their requests.
-
-This is done with the `anti oracle config set` command.
-
-
-```bash
-anti oracle config set  --min-test-duration MIN_TEST_HOURS --max-test-duration MAX_TEST_HOURS --agent-pkh PUBLIC_KEY_HASH
-```
-
-This will end up in a fact and so  we can inspect it with the `anti facts` command.
-
-```bash
-antij facts config
-```
-
 ## Updating the anti token
 
 The main responsibility of the oracle is to include change requests in the Antithesis token.
@@ -86,3 +69,24 @@ To delete the Antithesis token, you can use the `anti oracle token delete` comma
 ```bash
 anti oracle token delete
 ```
+
+## Publishing the oracle configuration
+
+Before requesters can request test-runs, the oracle should select the agent identity and in general expose validation parameters so that the requesters and the agent can pre-validate their requests.
+
+This is done with the `anti oracle config set` command.
+
+
+```bash
+anti oracle config set  --min-test-duration MIN_TEST_HOURS --max-test-duration MAX_TEST_HOURS --agent-pkh PUBLIC_KEY_HASH
+```
+
+In this situation the oracle is acting like a user and so this request will end up in the Antithesis token as a request for change.
+
+*Apply the token update command to commit the request to the Antithesis token*
+
+This will end up in a fact and so anyone can inspect it with the `anti facts` command.
+
+```bash
+antij facts config
+```

cli/docs/requester-role.md

@@ -16,37 +16,121 @@ Be careful that there is no imperativity here, so i.e. you cannot unregister a u
 
 ### Registering a user public key
 
-To register yourself as a user, you can use the `anti requester register-user` command.
+To register yourself as a user, you can use the `antij requester register-user` command.
 
 ```bash
-anti requester register-user --platform github --username alice --pubkeyhash AAAAC3NzaC1lZDI1NTE5AAAAIO773JHqlyLm5XzOjSe+Q5yFJyLFuMLL6+n63t4t7HR8
+antij requester register-user --platform github --username alice --pubkeyhash AAAAC3NzaC1lZDI1NTE5AAAAIO773JHqlyLm5XzOjSe+Q5yFJyLFuMLL6+n63t4t7HR8
 ```
 
 As with all other requests, once submitted regularly you have to wait for the oracle to merge your request into the Antithesis token.
 
-You can use the `anti token` command to inspect your pending requests in the Antithesis token.
+You can use the `antij token` command to inspect your pending requests in the Antithesis token.
 
-You can use the `anti facts` command to query the Antithesis token and see if your user is part of the facts.
+You can use the `antij facts` command to query the Antithesis token and see if your user is part of the facts.
 
 ```bash
-anti token | jq '.result.requests' "
+antij token | jq '.result.requests' "
 ```
 
 Until your requests is there, you cannot proceed with the next steps.
 
-As with all requests to an mpfs you can retract your request using the `anti retract` command, anytime before the oracle merges it into the Antithesis token.
+As with all requests to an mpfs you can retract your request using the `antij retract` command, anytime before the oracle merges it into the Antithesis token.
 
 Get the `outputRefId` of your request from pending requests command output and use it to retract your request
 
 ```bash
-anti retract -o 9ec36572e01bca9f7d32d791a5a6c529ef91c10d536f662735af26311b2c8766-0
+antij retract -o 9ec36572e01bca9f7d32d791a5a6c529ef91c10d536f662735af26311b2c8766-0
 ```
-ATM the oracle is not able to justify a request rejection. But anti cli will apply the oracle validation before submitting it, so rejections will be caught before submitting the request.
+ATM the oracle is not able to justify a request rejection. But antij cli will apply the oracle validation before submitting it, so rejections will be caught before submitting the request.
 
 ### Unregistering a user public key
 
-To unregister a user, you can use the `anti requester unregister-user` command.
+To unregister a user, you can use the `antij requester unregister-user` command.
 
 ```bash
-anti requester unregister-user --platform github --username alice --pubkeyhash AAAAC3NzaC1lZDI1NTE5AAAAIO773JHqlyLm5XzOjSe+Q5yFJyLFuMLL6+n63t4t7HR8
+antij requester unregister-user --platform github --username alice --pubkeyhash AAAAC3NzaC1lZDI1NTE5AAAAIO773JHqlyLm5XzOjSe+Q5yFJyLFuMLL6+n63t4t7HR8
 ```
+
+### Registering a role
+
+This is necessary to register a user as a github repository antitheisis test requester.
+
+Before you do this make sure your repository CODEOWNERS file contains a line like this:
+
+```
+antithesis: @your-github-username
+```
+
+You  can have as many user as you want but registering them as test-run requesters has to be done one by one.
+
+To register a role, you can use the `antij requester register-role` command.
+
+```bash
+antij requester register-role --platform github --username alice --repository yourorg/yourrepo
+```
+
+> Registering a role is not enough to gain rights to request test-runs. Your repository have to be white-listed by the agent. This requires you to get in contact with the agent and ask them to white-list your repository.
+
+### Unregistering a role
+
+```bash
+antij requester unregister-role --platform github --username alice --repository yourorg/yourrepo
+```
+
+## Test-runs
+
+
+### Setup
+
+Once you are registered as a user and a role, you can request test-runs.
+
+Before doing that make sure you have a commit in your repository containing a directory with "valid" test assets inside.
+
+You can obtain a set of standard test assets by running the following command:
+
+If you are in your repository directory, you can run:
+
+```bash
+antij requester generate-assets -D ./path/to/your/test/directory
+```
+
+Once you modified them you can try to run them locally  with the `antij requester test-run` command.
+
+```bash
+antij agent test-run -D ./path/to/your/test/directory
+```
+
+Then commit and push the changes to your repository.
+
+### Requesting a test-run
+
+Before proceding be careful to set the necessary signing assets in your environment variables.
+```bash
+  Which key selector to use from the SSH file
+  env: ANTI_SSH_KEY_SELECTOR STRING
+
+  Path to the SSH private key file
+  env: ANTI_SSH_FILE FILEPATH
+
+  Password to the decrypt the SSH private key
+  env: ANTI_SSH_PASSWORD STRING
+```
+
+The file at ANTI_SSH_FILE FILEPATH is the encrypted ssh private key matching the user registration.
+
+To request a test-run, you can use the `antij requester create-test` command.
+```bash
+antij requester create-test --platform github --username alice --repository yourorg/yourrepo --directory ./path/to/your/test/directory --commit your_commit_hash --try 1 --duration 2
+```
+
+You can request multiple test-runs for the same commit but you have to specify a different `--try` number for each request.
+
+### Checking the test-run status
+
+You can check the status of your test-run requests with the `antij facts test-run` command.
+
+```bash
+antij facts test-run pending
+```
+
+

cli/src/User/Requester/Options.hs

@@ -118,7 +118,7 @@ requesterCommandParser =
             $ Box <$> addRoleOptions
         , command "unregister-role" "Remove a user from a repository"
             $ Box <$> removeRoleOptions
-        , command "generate-asssets" "Generate assets for a test run"
+        , command "generate-assets" "Generate assets for a test run"
             $ Box . GenerateAssets <$> downloadAssetsDirectoryOption
         ]