Commands

There are two ways to make a Cmdop machine do something from code. Ask the agent when you want an outcome described in your own words and it can adapt to get there. Run a literal command when you already know the exact invocation. Either way the machine’s permission policy decides what is allowed.

There are two ways to make a machine do something, and picking the wrong one is the usual source of trouble.

Choose the command shape

Ask the agent when the outcome matters more than the exact invocation — it can look around, adapt, and explain. Run a literal command when you already know exactly what to execute and want nothing between you and it.

Ask the agent

text = await client.machines.ask(
    machine_id,
    "Find which service is holding port 8080 and report it. Do not stop it.",
).collect()

This is the higher-leverage form: the agent has the machine’s tools and can work through several steps. It streams as it goes — see Streaming.

The machine’s permission policy still applies to everything the agent tries. A request that needs a permission the machine has not granted is refused there, not in your client — see Permissions.

Run a literal command

From the terminal, against this host’s own relay:

cmdop connect exec <machine> -- uptime

For an interactive terminal on a machine behind a public or own-domain relay, attach instead — see Interactive attach.

Long-running work does not need you attached

Work continues on the machine when your process exits. Start it, disconnect, and read the result out of the session later — see Sessions. That is usually a better shape for CI than holding a connection open for the duration.

To make work happen at a particular time instead, see Schedules.

Related

• Streaming
• Interactive attach
• Programmatic access

Common questions

How do I run a command on a machine from code?

Ask the machine’s agent when the outcome matters more than the exact shell line. Use a literal command only when you already know exactly what to execute and want that command’s output and exit status.

Is a literal command better for CI?

Not always. For long-running work, start the work in a durable session and read the result later instead of holding a process open for the whole run.

Do permissions still apply to API commands?

Yes. The target machine’s permission policy decides what the agent or command may do. A refusal comes from the machine boundary, not from the client code.