CLI
Run any command from inside an agent repository (except new).
Commands that change the agent — routines, skills, plugins, credentials — edit files in the repository, not a running container. Local runs see the change immediately; a deployed agent runs the copy baked into its image and picks the change up on the next rebuild and redeploy (see Deploying your agent).
openroutines new <path> create a new agent repository
openroutines configure fill in openroutines.yml
openroutines check validate the agent; made for CI
openroutines status show what the agent has and still needs
openroutines knowledge inspect and summarize knowledge from origin
openroutines usage token use and reported cost per routine (--json)
openroutines sync pull the agent's latest knowledge from origin (--push)
openroutines routines <command> new, list, run, edit, activate, deactivate, remove
openroutines skills <command> new, list, remove
openroutines plugin <command> add, list, update grouped plugin bundles
openroutines credentials <cmd> set, list, remove
openroutines supervise run the scheduler (container entrypoint)
openroutines update bump the pinned framework version
openroutines version print the version
new
openroutines new <path>
Creates a fresh git repository with the agent’s skeleton: openroutines.yml, a starter check-in routine, an empty skills/ directory, AGENTS.md (with CLAUDE.md symlinked to it), a README.md, a generated avatar, a baseline opencode.json permission policy, .gitignore and .dockerignore, a Dockerfile, and the pinned framework version. It also generates the master key that encrypts the agent’s credentials, in master.key, kept out of the repository.
configure
openroutines configure
Idempotent — run it whenever. Fills in openroutines.yml (name, owner, timezone, default model) and reports anything the agent still needs.
check
openroutines check
Validates config, frontmatter, schedules, credential wiring, and config drift. When an agent-owned routine overrides a same-named plugin routine, check names the shadowed plugin path. Made for CI: run it on every push.
status
openroutines status
Shows what the agent has and what it still needs: its name, owner, and timezone, its default model, the framework version it pins against the binary you’re running, master key state, routines with their schedules, skills, and knowledge sync state. Token usage appears once there are runs to count.
Each routine also carries whatever scheduling state the supervisor has recorded: the watermark (how far its schedule is accounted for), a pending run with the attempts it has spent, and a circuit-breaker cool-down in place of a next fire time, since a routine sitting one out won’t honor it. Nothing under a routine means the supervisor has never seen it. The counts in parentheses are its declared grants.
A pending run also says what becomes of it:
next attempt <time>— the last attempt failed and the run is backing off.still in flight— the attempt is running now.due now— the retry is already owed, or no attempt has touched the run yet.budget spent— every attempt is gone; the next tick abandons the run and files a task.held— the routine is inactive or declares neither a schedule nor a trigger, so nothing is coming to advance the run. Activating it releases the run.
All of this comes from the knowledge branch as your checkout last fetched it, and status says when that reading is behind origin.
knowledge
openroutines knowledge open the interactive explorer
openroutines knowledge summarize [--since 24h] compose a briefing of recent work
openroutines knowledge list [path] [--json] list snapshot files
openroutines knowledge show <path> print one snapshot file
openroutines knowledge stats [--json] snapshot size and history
Fetches a read-only snapshot of origin/knowledge without adopting it into local knowledge/. In a terminal, the bare command opens a small interactive explorer; piped, it prints the overview and the direct-command help. Every view says when the local worktree is behind, ahead, divergent, or uncommitted.
summarize renders the last 24 hours of knowledge changes plus the current knowledge and routine schedule, through the agent’s default model, as Recently, Next, and Waiting on a human. --since sets a different window, and --yes skips the confirmation prompt for scripts.
usage
openroutines usage [--json]
Token use and reported cost per routine. --json emits the machine-readable form for scripts and monitors.
sync
openroutines sync [--push]
Reconciles knowledge/ with origin. A deployed agent writes its knowledge on the knowledge branch, and git pull in the agent repository moves the remote-tracking ref without touching the knowledge worktree, so a checkout keeps reading old knowledge until you sync it. Neither status nor usage syncs on its own; both say when yours is behind.
Syncing is how you adopt knowledge for local curation; openroutines knowledge inspects or summarizes origin without changing the worktree. After a sync, the knowledge files under knowledge/ are ordinary Markdown, and knowledge/ledgers/check-in.md holds the last check-in it delivered. For one composed right now, openroutines routines run check-in echoes a fresh report without consuming anything.
Sync fast-forwards when you’re behind and rebases local commits when both sides moved, but resolves nothing itself: a conflicting rebase is aborted and left for you to redo by hand inside knowledge/, and rewritten upstream history is refused outright. --push also publishes local knowledge commits.
A refusal also reports whether the deployed agent stranded knowledge on refs/openroutines/blocked, a snapshot of what a blocked supervisor couldn’t write to the branch, usually carrying the task that explains the block. Sync fetches that ref for you, so git -C knowledge show refs/openroutines/blocked:tasks.md reads it. Repairing the branch is what puts the state back on a container that’s still running, and the ref is deleted; if that container is gone, take what you want from the snapshot and drop the ref with git push origin :refs/openroutines/blocked.
routines
openroutines routines new <name> create a routine (inactive until you activate it)
openroutines routines list names, schedules, grants
openroutines routines run <name> [--write-knowledge] [--rehearse [scenario]]
run once now; optionally settle knowledge or rehearse
openroutines routines edit <name> open in $EDITOR, validate on close
openroutines routines activate <name> set active: true
openroutines routines deactivate <name> set active: false
openroutines routines remove <name> delete the routine and its scheduling state
A routine that does not load still holds its name: new refuses rather than overwrite it, run reports the parse error instead of “no routine”, and edit and remove operate on the file so you can fix or drop it.
run always has the routine’s declared credentials and tools and may perform external actions. It is not a dry run. A manual run discards its knowledge writes and run record by default, so iterating from the terminal never teaches the agent or consumes its change feed by accident; --write-knowledge makes the run count. --rehearse is the read-only path (see Rehearsals), and check validates without acting at all.
Deactivating a routine that is misbehaving in production stops it at the next redeploy, not the next tick — the deployed supervisor keeps reading the copy in its image until then.
skills
openroutines skills new <name> scaffold a blank skill
openroutines skills new <git-url | owner/repo> [--path <sub/dir>]
vendor a skill from a git repository
openroutines skills list skills and which routines use them
openroutines skills remove <name> refuses while any routine declares it
plugin
openroutines plugin add <git-url | owner/repo | local-dir> [--path sub/dir] [--yes]
openroutines plugin list
openroutines plugin update <name> [--yes]
add shows the bundle’s declared authority and vendors it under .openroutines/plugins/<name>/ after you confirm; installed routines land inactive. list shows installed plugins. update fetches the recorded source and three-way merges upstream changes against your vendored copy. --yes is required when stdin is not interactive.
credentials
openroutines credentials list credential names and which routines declare them
openroutines credentials set <name> add or replace one value (prompted, hidden)
openroutines credentials remove <name> refuses while any routine declares it
set writes the encrypted store in the repository. A deployed agent decrypts the copy in its image, so a rotated value reaches production with the next rebuild and redeploy — until then, runs keep using the old one.
supervise
openroutines supervise
Runs the scheduler. This is the container entrypoint; you rarely run it by hand.
update
openroutines update
Brings the agent up to the version of the openroutines binary you’re running: bumps the pin in .openroutines/version, rewrites the Dockerfile’s base-image tag, and offers other framework-owned file changes interactively with a diff.
version
openroutines version
Prints the version. Also --version / -v.