feat: add ricochet app instances {id} and ricochet app stop-instance {id} {pid}

[JosiahParry]

This PR adds two new commands:

• ricochet app instances to list instances for an app
• ricochet app stop-instance will stop a running instance

ricochet app instances

Table output

json output

cli ⚡  ricochet app instances 01KP1BV2ZFXAR1HQF5C1KCSATE -S vm --format json
[
  {
    "instance_id": "01KPXTDBN2SD3K3FW4JWB9MZ94",
    "connections": 8,
    "created_at": "2026-04-23T18:42:37.095920877Z",
    "last_connection": "2026-04-23T18:42:42.181Z"
  },
  {
    "instance_id": "01KPXTDC819527KBJGBR8320C2",
    "connections": 8,
    "created_at": "2026-04-23T18:42:37.681104595Z",
    "last_connection": "2026-04-23T18:42:46.644Z"
  },
  {
    "instance_id": "01KPXTDCMKDTB22ZJQ0GVDM0QF",
    "connections": 4,
    "created_at": "2026-04-23T18:42:38.006430514Z",
    "last_connection": "2026-04-23T18:42:48.882Z"
  },
  {
    "instance_id": "01KPXTD21R1Q162PRWFS39572Z",
    "connections": 8,
    "created_at": "2026-04-23T18:42:27.182329136Z",
    "last_connection": "2026-04-23T18:42:36.266Z"
  }
]

yaml output

cli ⚡  ricochet app instances 01KP1BV2ZFXAR1HQF5C1KCSATE -S vm --format yaml
- instance_id: 01KPXTDBN2SD3K3FW4JWB9MZ94
  connections: 8
  created_at: 2026-04-23T18:42:37.095920877Z
  last_connection: 2026-04-23T18:42:42.181Z
- instance_id: 01KPXTDC819527KBJGBR8320C2
  connections: 8
  created_at: 2026-04-23T18:42:37.681104595Z
  last_connection: 2026-04-23T18:42:46.644Z
- instance_id: 01KPXTDCMKDTB22ZJQ0GVDM0QF
  connections: 4
  created_at: 2026-04-23T18:42:38.006430514Z
  last_connection: 2026-04-23T18:42:48.882Z
- instance_id: 01KPXTD21R1Q162PRWFS39572Z
  connections: 8
  created_at: 2026-04-23T18:42:27.182329136Z
  last_connection: 2026-04-23T18:42:36.266Z

ricochet app stop-instance

cli ⚡  ricochet app stop-instance 01KP1BV2ZFXAR1HQF5C1KCSATE 01KPXTDCMKDTB22ZJQ0GVDM0QF -S vm
✓ Instance 01KPXTDCMKDTB22ZJQ0GVDM0QF stopped

[pat-s]

The following semantics would feel more natural to me:

ricochet app instance list
ricochet app instance stop

To me, any hyphen in a subcommand or lower feels somewhat unnatural. The detailed issue is that it's a mix of "action" (stop) and "scope" (instance) (for stop-instance) wheres instances is a single entity which implies the "action" to list something.

[JosiahParry]

@pat-s any idea why crow is immediately failing the test pipeline?

[JosiahParry]

Got it. Had to restart the docker worker

[pat-s]

Got it. Had to restart the docker worker

I've added some hardening recently in Crow to make the agent more resilient and recover on it's own - hopefully!

[pat-s]

Looking at it again, I wonder if we should just simplify to

ricochet app list
ricochet app stop <ID> <PID>

The additional instance sub-menu isn't of immediate use to me right now.

This current state is certainly better than the previous one with stop-instance though it feels like that we would need another submenu besides instance to justify this one.
WDYT?

[JosiahParry]

Lol okay so you want ricochet app list <ID> and ricochet app stop <ID> <PID>? In both cases <ID> is optional inferred from the _ricochet.toml if not set. If not set and no _ricochet.toml found error

[pat-s]

ricochet app list would list all apps a user has access to so they can find their IDs? Alternatively also ricochet apps list (note the 's').
ricochet app info <ID> would return details of an app?
If run in a directory with a _ricochet.toml we could auto-infer the ID, yes.

How about having ricochet app stop <ID> stopping all processes by default and only when PID is passed it stops only a single process?

[JosiahParry]

I think we're getting a bit of scope creep or mixing concepts right now.

What about:

• ricochet app instances to list all instances
• ricochet app stop stops all instances of the app
• ricochet app stop <PID> would stop a specific instance.

An app will have multiple instances supporting it. We want to be able to list these instances to get the PID, connection count, age, etc.

I think ricochet user apps would be better for listing all apps as well as filters like this: ricochet user tasks --role=owner,admin but that's somewhat unrelated here.

[pat-s]

One point is about re-using existing/common terms in/from other sub-commands to make usage easier.

I don't think ricochet app instances is intuitive. ricochet app list could also be an alias to ricochet user apps.

Both could/should then list all existing app instances and, if known, their respective servers they live on. In a brief and concise format without too much detail. These details can be shown with the respective app detail commands then.

I see why this might seem to go a bit off-topic but I don't think it necessarily is - it's a fundamental discussion which lays the foundation for the design of other related sub-commands then.

I am OK with the semantics of ricochet app stop proposed in your latest reply!

[JosiahParry]

I don't think ricochet app list should list every single app a user has as well as every single running instance of that app. That would require pagination undoubtedly.

If app is the individual item subcommand then the list should list instances.
If one want their own apps it should likely go under ricochet user apps --role owner

[pat-s]

If app is the individual item subcommand then the list should list instances.

"If app is the individual item subcommand then the list should list app instances of the selected ricochet server."

Agreed?

[JosiahParry]

Maybe? The selected ricochet server is always a requirement for the cli. I don't think we should query multiple servers at the same time.

If there is an app with ID. ricochet app list will show the running processes for that application.

[pat-s]

Alright let's do it then :) I'll "complain" later on if it "feels wrong" 🤓