Medplum Agent Commands exposed in CLI

[rahul1]

Use Case

Some DevOps engineers primarily work with CLI tooling and shell scripts, rather than rest API calls.

To help them, we want to expose all the Agent maintenance commands as CLI commands. This will also help to integrate into monitoring tools such as BetterStack.

Proposal

medplum agent push <args..> [--wait-for-response]
medplum agent ping <host> [pingCount]
medplum agent status <agentId>
medplum agent bulk-status [criteria]

# When added:
medplum agent reload-config <agentId1>[agentId2..agentIdN]
medplum agent upgrade <version> <agentId1>[agentId2..agentIdN]

[rahul1]

medplum agent push <args..> [--wait-for-response]

• Do we need an agentId for this?
• I think this should wait by default, and have a flag to make it async (mirrors the TS API)

medplum agent ping <host> [pingCount]

• don't we need the agent id for this?

medplum agent reload-config <agentId1>[agentId2..agentIdN]
medplum agent upgrade <version> <agentId1>[agentId2..agentIdN]

For each of these, consider an optional [criteria] input as well, similar to your bulk status endpoint. Users will appreciate not having to have an explicit list of ids

[rahul1]

@ThatOneBro Got a proposal for you. What do you think?

All commands can take in a list of agentIds or a criteria field, with --criteria as a flag

medplum agent status  <agentId1>[agentId2..agentIdN]  OR medplum agent status --criteria <criteria>
medplum agent reload-config <agentId1>[agentId2..agentIdN] OR medplum agent reload-config --criteria <criteria>
medplum agent upgrade <version> <agentId1>[agentId2..agentIdN]  OR medplum agent upgrade --criteria <criteria>

[ThatOneBro]

• Do we need an agentId for this?

Yes you're right, should be first param

• I think this should wait by default, and have a flag to make it async (mirrors the TS API)

I believe this closely matches the TS API already, Agent$push does not wait unless you pass waitForResponse: true 😅 I think this is due to the original behavior being not to wait for response so this was tacked on later

@ThatOneBro Got a proposal for you. What do you think?

All commands can take in a list of agentIds or a criteria field, with --criteria as a flag

medplum agent status  <agentId1>[agentId2..agentIdN]  OR medplum agent status --criteria <criteria>
medplum agent reload-config <agentId1>[agentId2..agentIdN] OR medplum agent reload-config --criteria <criteria>
medplum agent upgrade <version> <agentId1>[agentId2..agentIdN]  OR medplum agent upgrade --criteria <criteria>

This was my original thought too but I think we should keep bulk-status separate from status since their return shapes are quite a bit different. status is a Parameters resource and bulk-status is a Bundle<Parameters<Agent | Parameters>>, which may lead to confusion about how to parse it? Although I guess maybe its fine?

In regards to upgrade or reload-config taking agent IDs or criteria, maybe that's fine? I think how it would be implemented under the hood is just call $reload-config with ?_id={id1},{id2}, which maybe is not that bad and has some added convenience? I think the only thing that's worth considering is if the command parsing becomes more complex if other args are removed when a flag is added. Nothing we can't figure out but wonder if the tradeoff is worth it. (I could go either way at this point) What do you think?

[rahul1]

I believe this closely matches the TS API already, Agent$push does not wait unless you pass waitForResponse: true 😅 I think this is due to the original behavior being not to wait for response so this was tacked on later

Oh awesome! If they're already consistent, then all good

In regards to upgrade or reload-config taking agent IDs or criteria, maybe that's fine? I think how it would be implemented under the hood is just call $reload-config with ?_id={id1},{id2}, which maybe is not that bad and has some added convenience? I think the only thing that's worth considering is if the command parsing becomes more complex if other args are removed when a flag is added. Nothing we can't figure out but wonder if the tradeoff is worth it. (I could go either way at this point) What do you think?

Yeah I had similar thoughts. using _id under the hood is clean. Some alternate options I considered:

1. make the first arg do double duty (agentIdORCriteria), and enforce that the criteria starts with Agent?.... IMO this feels a little too magical.
2. Drop the criteria feature altogether, and keep it simple

The main nice thing about using "criteria" is that any script that uses the CLI command doesn't need to be updated when a new Agent is onboarded. So devops/CLI tooling can maintain a pretty stable command. Given that benefit, I think it's worth doing

[rahul1]

This was my original thought too but I think we should keep bulk-status separate from status since their return shapes are quite a bit different. status is a Parameters resource and bulk-status is a Bundle<Parameters<Agent | Parameters>>, which may lead to confusion about how to parse it? Although I guess maybe its fine?

What would you think about always returning a Bundle, but just sometimes it only has one entry?
My thinking was that reducing one command might make the tools easier to grok, and makes less surface area