Skip to content

README.md

Latest commit

 

History

History
415 lines (267 loc) · 10.8 KB

README.md

File metadata and controls

415 lines (267 loc) · 10.8 KB

devos CLI

Talk is cheap, show me your agent system.

Product README | Operator Guide | Architecture | Security

The devos CLI runs agentic development workflows from your terminal.

devos is the command surface for onboarding, daemon startup, workflow runs, task intake, status inspection, skills, plugins, and release helpers. It is the local entrypoint for the same project-aware orchestration described in the root README: brainstorm, plan, implement, test, review, and report progress while keeping the operator in control.

Use this README as the command reference. For the product story, features, architecture overview, and problems solved, start with ../../README.md.

Quick Start

Install the published CLI:

curl -fsSL https://devos.ing/cli | bash

Run guided onboarding, start the local daemon, validate setup, then run one scoped workflow:

devos onboard
devos daemon
devos onboard --check
devos run --issue ENG-123

Command Reference

Use devos ... after linking or installing the package bin.

Help

Purpose: print CLI usage and available commands.

Syntax:

devos help
devos --help
devos -h

Output shape:

  • Multi-line plain text usage guide.

Usage notes:

  • No project config is required to render help.

onboard

Purpose: run guided environment onboarding, or validate onboarding prerequisites.

Syntax:

devos onboard [--check]

Options:

  • --check: run onboarding validation checks without opening the interactive wizard.

Output shape:

  • Human-readable onboarding/check logs written to stdout/stderr.

Usage notes:

  • onboard runs the interactive wizard.
  • Default onboarding enables per-issue isolated git worktrees for local runs.
  • onboard --check performs validation only.

run

Purpose: run workflow orchestration for one issue or the configured queue.

Syntax:

devos run [--issue <LINEAR_KEY_OR_URL>] [--poll|--poll-forever] [--no-exit-when-idle] [--concurrency <N>] [--poll-interval-ms <MS>] [--max-poll-cycles <N>] [--isolated-worktrees]

Options:

  • --issue <LINEAR_KEY_OR_URL>: scope run to a specific Linear issue.
  • --poll: continue polling for new work.
  • --poll-forever: daemon-friendly polling mode; implies --poll, ignores configured max cycles, disables idle exit, and cannot be combined with --max-poll-cycles.
  • --no-exit-when-idle: disable automatic exit while idle.
  • --concurrency <N>: positive integer worker concurrency.
  • --poll-interval-ms <MS>: positive integer poll interval.
  • --max-poll-cycles <N>: positive integer max polling cycles.
  • --isolated-worktrees: enable isolated worktree mode.

Output shape:

  • Streaming human-readable workflow logs and stage progress.

Usage notes:

  • Numeric options must be positive integers.

status

Purpose: inspect persisted run state for one issue.

Syntax:

devos status --issue <LINEAR_KEY>

Options:

  • --issue <LINEAR_KEY>: required issue key.

Output shape:

  • If state exists: pretty-printed JSON object including persisted run fields plus stageDisplay.
  • If state does not exist: No run state found for <ISSUE_KEY>.

Usage notes:

  • --issue is required.

release

Purpose: inspect GitHub Releases and run the tag-only release marker flow.

Syntax:

devos release list [--limit <N>] [--repo <OWNER/REPO>]
devos release tag <TAG> [--message <MESSAGE>] [--remote <REMOTE>]

Options:

  • --limit <N>: positive integer number of GitHub Releases to list.
  • --repo <OWNER/REPO>: optional GitHub repository for release list.
  • --message <MESSAGE>: annotated tag message for release tag.
  • --remote <REMOTE>: git remote to push to; defaults to origin.

Output shape:

  • release list streams gh release list output.
  • release tag streams git tag and git push output.

Usage notes:

  • release tag only creates and pushes an annotated git tag. It does not create a GitHub Release and does not publish npm packages.
  • Use gh release create <TAG> later if you want a GitHub Release entry from an existing tag.

task create

Purpose: generate a Linear backlog issue from a loose request through task intake.

Syntax:

devos task create [<REQUEST>] [--request <TEXT|->] [--non-interactive] [--max-clarification-rounds <N>] [--clarifications-json <JSON>]

Parameters and options:

  • <REQUEST>: optional positional request text.
  • --request <TEXT|->: request text; use - to read from stdin.
  • --non-interactive: disable interactive clarifying questions.
  • --max-clarification-rounds <N>: optional positive integer cap.
  • --clarifications-json <JSON>: optional JSON array of { "question": "...", "answer": "..." }.

Output shape:

  • On success: Created Linear task <IDENTIFIER>: <URL>.
  • On unresolved intake: a multi-line message starting with Task requirements are still unclear; no Linear issue was created. and listing remaining questions.

Usage notes:

  • In non-interactive mode, a non-empty request is required, provided either as positional <REQUEST> or --request <TEXT>.
  • In non-interactive mode, --request - is not allowed.
  • --clarifications-json must be valid JSON array entries with non-empty question and answer strings.

skills list

Purpose: list skills for the configured skills root.

Syntax:

devos skills list

Output shape:

  • If skills exist: one tab-separated line per skill: <name>\t<title>\t<description|->
  • If none exist: No skills found in <skillsRootPath>.

skills add

Purpose: create a new skill document in the configured skills root.

Syntax:

devos skills add --title "<TITLE>" --description "<DESCRIPTION>" --content "<CONTENT>"

Options:

  • --title <TITLE>: required skill title.
  • --description <DESCRIPTION>: required skill description.
  • --content <CONTENT>: required skill body content.

Output shape:

  • Added skill <name> at <path>.

skills update

Purpose: update skill metadata/content by skill name.

Syntax:

devos skills update <NAME> [--title "<TITLE>"] [--description "<DESCRIPTION>"] [--content "<CONTENT>"]

Parameters and options:

  • <NAME>: required skill name.
  • --title <TITLE>: optional new title.
  • --description <DESCRIPTION>: optional new description.
  • --content <CONTENT>: optional new content.

Output shape:

  • Updated skill <name> at <path>.

Usage notes:

  • At least one of --title, --description, or --content is required.

skills remove

Purpose: remove a skill by name from the configured skills root.

Syntax:

devos skills remove <NAME>

Parameters and options:

  • <NAME>: required skill name.

Output shape:

  • Removed skill <name> from <path>.

After linking/installing the package bin, you can also use devos ... directly.

plugins list

Purpose: list bundled CLI plugins.

Syntax:

devos plugins list [--enabled]

Options:

  • --enabled: show only plugins explicitly enabled in local devos config.

Output shape:

  • One tab-separated line per plugin: <id>\t<title>\t<enabled|disabled>

plugins show

Purpose: print a bundled plugin template as formatted JSON.

Syntax:

devos plugins show <PLUGIN_ID>

plugins install

Purpose: show safe install instructions for a bundled plugin.

Syntax:

devos plugins install <PLUGIN_ID>

Usage notes:

  • V1 does not execute install commands or remote scripts.
  • Templates keep install commands structured for a future trusted installer.

plugins enable

Purpose: persist a bundled plugin as enabled in local devos config.

Syntax:

devos plugins enable <PLUGIN_ID>

Usage notes:

  • Enabled plugin IDs are stored in local sqlite env as DEVOS_ENABLED_PLUGINS.
  • Codex plugin IDs declared by a template are stored in CODEX_PLUGINS and passed to Codex as plugins."<id>".enabled=true.

plugins check

Purpose: run local validation checks declared by a bundled plugin template.

Syntax:

devos plugins check <PLUGIN_ID>

Output shape:

  • One tab-separated result line per check: <PASS|FAIL>\t<title>\t<expected-or-output>

CLI Plugin Templates

CLI plugin templates live under templates/plugins/. They are JSON documents used by devos plugins list/show/install/enable/check.

Use templates/plugins/plugin.template.json for new entries. Each template should include:

  • title: display name shown to operators.
  • description: short explanation of when to use the plugin.
  • functional: readable capability list.
  • source: GitHub repository or script location.
  • install: install steps as structured { "command": "...", "args": [...] } entries.
  • enable: config, environment, or PATH changes needed to activate it.
  • checks: validation commands the CLI can run later.
  • tokenOptimization: how the plugin saves tokens and how to measure it.

RTK is documented as the first token-optimization plugin in templates/plugins/rtk-token-optimizer.json. It models a binary plugin: inspect install notes with devos plugins install rtk-token-optimizer, place it on PATH, enable it with devos plugins enable rtk-token-optimizer, validate it with devos plugins check rtk-token-optimizer, and opt in by prefixing agent shell commands with rtk.

Keep plugin templates small and declarative. Prefer structured command arrays over shell strings so future workflow code can execute them without parsing.

Configuration Notes

  • Guided onboarding stores local secrets in ~/.devos/config/env.sqlite (and writes .env for compatibility) and writes ~/.devos/config/instance.config.json for the local trusted instance.
  • Local instance data lives under ~/.devos/instances/default.
  • Docker-isolated Codex execution status and caveats (ROY-95): ../../docs/RELIABILITY.md#docker-isolated-codex-execution

For runtime config resolution, polling, env vars, and routing behavior, use:

Quality Checks

Run these before opening or updating a PR:

bun run check
bun run typecheck
bun test

Star History

Star History Chart