poema cloud

CLI

poema drives poema from a shell, on Node 22.19 or later. It is not on npm: this site carries its package.

The command line package is coming; the HTTP API works today.

It reads the same variables as the SDK, and takes manifests in YAML or JSON:

export POEMA_URL=https://127.0.0.1:7070
export POEMA_API_KEY=poema_ns_...

echo '{"apiVersion": "poema.dev/v1alpha1", "kind": "Task", "metadata": {"name": "hello"},
  "spec": {"command": ["sh", "-c", "echo hello; sleep 600"], "gateway": {"name": "default"}, "debug": true}}' | poema apply -f -
poema get tasks
poema logs hello
poema terminal hello             # a shell in it (debug: true turns the terminal on)
poema forward hello 3000:3000    # 127.0.0.1:3000 here, to port 3000 inside it

Commands

  • poema apply -f FILE creates or updates the resources in a file, - for stdin.
  • poema get KIND [NAME] [-o json|yaml] lists or shows tasks, workspaces, gateways, models or secrets.
  • poema describe task NAME shows an instance's spec, status, usage and recent activity, its egress included.
  • poema watch task NAME prints a line per change of its status.
  • poema logs NAME [-f] is its command's output.
  • poema exec NAME -- CMD [ARGS...] runs a command in it, when it was made with debug: true.
  • poema suspend NAME and poema resume NAME stop and restart it, and poema timeout NAME SECONDS resets its deadline.
  • poema delete KIND NAME deletes a resource, and for an instance waits until it is gone.
  • poema terminal NAME [--cwd DIR] opens a shell in it, in DIR or its first cloned repository, when it was made with debug: true.
  • poema forward NAME [LOCAL:]REMOTE listens on 127.0.0.1:LOCAL and carries each connection to 127.0.0.1:REMOTE inside it, also with debug: true.
  • poema secret set NAME KEY=VALUE ... stores a secret, and poema secret list shows their names and keys, never their values.
  • poema login and poema logout are for a server that signs users in through its own identity provider. poema cloud does not: use your API key.

Forking is the SDK's and the MCP server's for now.

An instance to work in

poema apply -f - <<'EOF'
kind: Task
metadata: {name: work}
spec:
  command: [sleep, infinity]
  gateway: {name: default}
  debug: true
EOF
poema exec work -- git clone --depth 1 https://github.com/octocat/Hello-World
poema exec work -- ls Hello-World
poema suspend work