Update CLI documentation for `run`, `status` and `reset` commands

[adrianbenavides]

trafficstars

Details of what the documentation should include can be found at https://github.com/build-trust/ockam/issues/4759

---

We love helping new contributors! ❤️ If you have questions or need help as you explore, please join us on Discord. If you're looking for other issues to contribute to, please checkout our good first issues.

[itsajay1029]

Please assign this issue to me @adrianbenavides

[itsajay1029]

Can guide me where I can get details of run, status and reset in ockam docs @adrianbenavides ??

[adrianbenavides]

Current status

All three commands have been updated recently to include a short about comment (the rust doc comments)

What's missing

• Code examples
• Optionally, the "long about" section

How to

The commands to update are: run, status and reset.

• reset and status commands: they have to be moved to their own directory and rename the files accordingly, just as the run command
• add a static directory with a after_long_help.txt file in it that will include the code examples. Most of the commands have this structure, and you can use them as a reference (space create, identity create, enroll)
• if you want to add the "long_about" section, you'll have to add a "long_about.txt" file within the static directory. Check out the aforementioned commands to see some examples

[itsajay1029]

I need to create two separate folders under src directory for reset and status ? Also, where do I get the code examples for the after_long_help.txt for each of the commands @adrianbenavides ?

[itsajay1029]

Please guide me on this @adrianbenavides

[adrianbenavides]

I need to create two separate folders under src directory for reset and status ?

That's right.

Also, where do I get the code examples for the after_long_help.txt for each of the commands @adrianbenavides ?

I'd recommend you to play around with those commands for a bit and read the docuemntation that we have in the code. The status and reset are pretty straightforward as they only have one optional argument. Ideally, we would like to have code examples for the different variants:

For the status command:

# To show the information about the system's enrolled Identities and Nodes
$ ockam status

# You can list all the identities passing the `--all` argument
$ ockam status --all

For the reset command:

# This will prompt you for confirmation before proceeding
$ ockam reset

# To confirm without prompting
$ ockam reset -y 

As for the run command, you have the high level defails of what it does here, and an example of the expected configuration file here. Note that, to run the previous example where tcp-inlets are created pointing to /project/default, you will have to run ockam enroll first to create a project in the ockam orchestrator. Check out the docs if you want to know more about this.

Let me know if you want more details about anything I mentioned! 👍

[itsajay1029]

Thanks. Will let you know if I stuck somewhere

[nazmulidris]

@itsajay1029 Thank you for taking the time to look at this issue. Since you’ve not had a chance we’re opening the issue up for other contributors.

[Wryhder]

I'd love to work on this issue if it's available. Could I be assigned to it?

[adrianbenavides]

Hi @Wryhder , sure! Since we created this issue we've been updating the commands. Probably the run command is in good shape, but the rest could be improved. Let me know if you need any help!

[Wryhder]

Hi @Wryhder , sure! Since we created this issue we've been updating the commands. Probably the run command is in good shape, but the rest could be improved. Let me know if you need any help!

@adrianbenavides Could you please help me with what the controller and project version information in the output of ockam status mean? Also, what is the controller? Is that the Orchestrator?

$ ockam status

    Controller version: 0.36.2
    Project version: 0.7.0

    Identities
    ───────────────────────────────────────────────────────────────────────
    ravishing-gnatcatcher (default):
      With Identifier [...]
      Was enrolled at [...] with email [...]
    careful-swiftlet:
      With Identifier [...]
      Is not enrolled

    Nodes
    ───────────────────────────────────────────────────────────────────────
    n1 (default):
      The node is UP, with PID [...]
      With route [...]
      [...]

BTW, ockam status --all throws an error. There seems to be just a --timeout option, per the docs here and the code. No --all option:

$ ockam status --all
error: unexpected argument '--all' found

Usage: ockam status [OPTIONS]

The status command lists all identities by default, enrolled and unenrolled.

I tested the --timeout flag too. No error, but it doesn't seem to do anything either. Default timeout stated in the CLI help is 5s. Ran ockam status --timeout 0.00000000000000000000000000000000000000000000002 but the command didn't time out. (I wondered if it was because I missing the unit, but ockam status --timeout 0.0000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000002s didn't time out either.) Am I using it incorrectly?

[Wryhder]

@adrianbenavides Hi! Just wanted to check if you've gotten the chance to read my previous comment.

Edit: Never mind about the controller and project version. (I looked up "network controller" and it looks to be the orchestrator. Project version is the version of the default project.)

[adrianbenavides]

Sorry @Wryhder I totally missed your previous comment.

BTW, ockam status --all throws an error. There seems to be just a --timeout option, per the docs here and the code. No --all option

A lot has changed since I wrote the details of this issue, so you can expect to find some discrepancies. The --all option was removed. The --timeout flag is only used to establish the secure channel, but not as the timeout to wait for a response.

I tested the --timeout flag too.

You can find here how the timeout arg is being parsed. Note that some of the data the status command returns is local, that's why the command doesn't fail if the timeout is reached, but instead, some data will be "null". For example, you can check that the timeout works if you set a tiny value (e.g. 1ms). You will see that the controller and project versions are N/A.

Could you please help me with what the controller and project version information in the output of ockam status mean? Also, what is the controller? Is that the Orchestrator?

The controller version is indeed the version of the Orchestrator Controller. The project version is just that, you can find more details about projects here.

[Wryhder]

@adrianbenavides Thanks for your response!

Note that some of the data the status command returns is local, that's why the command doesn't fail if the timeout is reached, but instead, some data will be "null". For example, you can check that the timeout works if you set a tiny value (e.g. 1ms). You will see that the controller and project versions are N/A.

This probably explains the behaviour I was asking about in the first item in my comment here (crossed out already). Could you take a look when you get the chance? I need some help with the last two items.