Develop

mobius groups its commands by the thing you're working on. This page tells you which group to reach for. For the exact commands and options, run mobius <group> --help, which always matches the version you have installed.

The groups

A few more exist for organization-wide administration: org-api-keys, org-actions, org-skills, principals, roles, and permissions. You'll meet those when you're setting up who can do what, not day to day.

Loops used to be called automations. If you find an old script calling mobius automations, that group is gone. mobius loops --help shows the replacement.

Sending a file instead of typing flags

Anything with more than a couple of fields is easier to keep in a file. Commands that create or update something take --file, in JSON or YAML:

mobius loops create \
  --project ridgeline \
  --file triage-tickets.yaml \
  --fields id,name,status \
  --output json

{
  "id": "loop_9q2m7x5v3p8n4r6t",
  "name": "Triage tickets",
  "status": "active"
}

Two things make this pleasant to live with:

• --dry-run prints the request without sending it. Use it every time you change the file. It costs nothing and catches typos before they become a half-created loop.
• --var KEY=value fills in blanks. Write ${CLIENT} in the file and pass --var CLIENT=ridgeline, and one file covers every client.

Flags you pass on the command line win over what's in the file.

Working with runs

Start a run. Runs are started by loop ID, which you can get from mobius loops list:

mobius runs start loop_9q2m7x5v3p8n4r6t \
  --project ridgeline \
  --fields id,status \
  --output json

{
  "id": "run_8q5m2x9v7p3n4r6t",
  "status": "queued"
}

Read what happened:

mobius runs list-events run_8q5m2x9v7p3n4r6t \
  --project ridgeline \
  --fields sequence,event_type \
  --output json

{
  "items": [
    { "sequence": 1, "event_type": "run.started" },
    { "sequence": 2, "event_type": "step.started" }
  ],
  "has_more": false
}

Pick a failed run back up from its last checkpoint, rather than starting over:

mobius runs resume run_8q5m2x9v7p3n4r6t \
  --project ridgeline \
  --reason "Provider recovered" \
  --fields id,status,attempt \
  --output json

{
  "id": "run_8q5m2x9v7p3n4r6t",
  "status": "running",
  "attempt": 2
}

attempt counts up each time you resume or retry, so you can tell a first run from a rescue. Recover a failed run covers when to resume and when to start over.

Working with conversations

mobius sessions list --project ridgeline
mobius sessions get <session-id> --project ridgeline
mobius sessions stream <session-id> --project ridgeline

stream holds the line open and prints the agent's reply as it arrives.

If an agent is working and heading the wrong way, you don't have to wait for it to finish. Send it a note mid-reply:

mobius sessions nudge <session-id> \
  --project ridgeline \
  --content "Draft the reply, but don't send anything to the client." \
  --fields id,status,delivery \
  --output json

{
  "id": "<nudge-id>",
  "status": "pending",
  "delivery": "current_turn"
}

current_turn means it reaches the agent during the reply it's writing now.

Working with data

mobius artifacts list --project ridgeline
mobius tables list --project ridgeline
mobius environments list --project ridgeline

Writing is per-resource, so ask the command what it wants:

mobius tables create --help
mobius tables upsert-row --help
mobius environments create --help

Running a worker

A worker is how Mobius reaches things it can't reach on its own, like a server inside a client's network. Start one:

mobius worker --project ridgeline

It logs a lot on startup. Two lines are the ones that matter, in this order:

level=INFO msg="starting worker" project=ridgeline ...
level=INFO msg="worker registered" worker_instance_id=<instance-id> heartbeat_cadence_seconds=<seconds>

The first says the process started. The second says Mobius knows about it and will send it work. Until you see the second one, nothing is happening.

By default it takes work from every queue in the project. Use --queues to narrow it when you're running more than one worker and want them doing different things.

The process stays in the foreground while it's connected, so leave the window open or run it as a service. A reconnect message now and then is normal, that's a brief network blip. Worry when worker registered never appears at all, or when it reconnects over and over without settling.

Secrets that print once

Commands that create an API key or a webhook secret show you the full value one time and never again. There's no "show it to me" command later, by design.

mobius api-keys create \
  --project ridgeline \
  --name ci-worker \
  --principal-id <principal-id> \
  --output json

{
  "id": "<key-id>",
  "name": "ci-worker",
  "key": "<one-time-api-key>"
}

Put it in your password manager or secret store before you close the terminal. If you lose it, the fix is to create a new key and delete the old one.

Next

• Install and sign in.
• Learn the conventions in the CLI overview.
• Use the interactive API reference when a command doesn't exist yet for what you need.