schwarm-cli 0.1.2 → 0.1.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 066e7d9d88f9e9d06311933b23308735d9856580de1f2d2dfc320d90f45f6deb
-  data.tar.gz: f46de7b54809c3283f14669c0727d308d6e5b8d24066c0e99618c7945b0b044f
+  metadata.gz: fda5a7c0a0a68a6e07573a5509cadb8ea7ff600f94a3feabf065317c332a9b40
+  data.tar.gz: bfd4c31bca63d5862c9df68514c8ab3bdeefb0a1ebbd944c316aeed4522a626d
 SHA512:
-  metadata.gz: 28ae5f67cdd2bbca5a04d1571171252adb36fd7eaccc489f8306038887c52e55c65fea6e348fc5af1ac849f5fd6725be49741d3f68cadfd863897d370fc9ac44
-  data.tar.gz: ace4db1afda31bcdc3b4555c7167c3259ec2723ec9a86f6750b9c6eb85ef4dcf26cc71f7e1e636b2882d510cb1e006daf277988851758467412811f445a9765c
+  metadata.gz: cf2aac68753184cd3ef7fcd28ff24eb75010b84237f2b661e76a00e1582ead6ad07b0789941f9d3c518bd40eadc34bea14d463bc83e7d69dfb62f68f165920a3
+  data.tar.gz: 9bdf3cbb26adecc1f40e90d681e9cb722bd2ae477cd7faa1ac258f3bf690cc77aa1374cb2744a8fe9bb6583b7b328b242f81e80f19ab79afa2dedad23c5d6b55

data/README.md

@@ -0,0 +1,68 @@
+# schwarm-cli
+
+Command-line interface for [Schwarm](https://github.com/getdexter/schwarm) — a
+distributed system that orchestrates Claude Code agents working on tasks in
+parallel. Wraps the Schwarm Public API v2 to manage tasks, repositories,
+skills, agents, and more.
+
+## Installation
+
+Requires Ruby >= 4.0.
+
+```bash
+gem install schwarm-cli
+```
+
+This installs the `schwarm` executable.
+
+## Configuration
+
+Run the interactive configuration once to point the CLI at your Schwarm
+server and save an API key:
+
+```bash
+schwarm configure
+```
+
+You'll be prompted for:
+
+- **Server URL** (defaults to `https://schwarm.getdexter.net`)
+- **API Key** — create one from your Schwarm server's API Keys page
+
+The credentials are saved to `~/.schwarm/config/<env>.json` and the connection
+is tested before saving.
+
+## Usage
+
+List top-level commands:
+
+```bash
+schwarm help
+schwarm tree         # full command tree
+schwarm version
+```
+
+Common workflows:
+
+```bash
+schwarm repos list
+schwarm tasks list
+schwarm tasks create --repo <REPO_ID> --name "Fix bug" --prompt "..." --status ready
+schwarm tasks show <TASK_ID>
+schwarm tasks handoff --repo <REPO_ID> --name "Continue WIP"
+```
+
+For the full set of agent-oriented workflows (dispatching tasks, DAGs,
+handoffs, monitoring, messaging), print the bundled skill:
+
+```bash
+schwarm skill
+```
+
+This is the same document AI agents read to learn how to drive the CLI, and
+it's kept in sync with the gem at [`cli/schwarm-skill.md`](schwarm-skill.md).
+
+## Links
+
+- [Schwarm repository](https://github.com/getdexter/schwarm)
+- [Source](https://github.com/getdexter/schwarm/tree/main/cli)

data/lib/schwarm_cli/client/user_messages.rb

@@ -4,7 +4,7 @@ module SchwarmCli
   class Client
     class UserMessages < Resource
       def create(task_id:, content:)
-        post("/api/v2/tasks/#{task_id}/messages", { user_message: { content: } }).body
+        post("/api/v2/tasks/#{task_id}/messages", { message: { content: } }).body
       end
     end
   end

data/lib/schwarm_cli/commands/agents.rb

@@ -4,13 +4,13 @@ module SchwarmCli
   module Commands
     class Agents < Base
       desc "list", "List repository agents"
-      option :repo, type: :string, desc: "Filter by repository ID"
+      option :repo, type: :string, desc: "Filter by repository ID, owner/repo, or GitHub URL"
       option :query, type: :string, desc: "Search by name"
       pagination_options
       def list
         handle_errors do
           data = fetch_paged do |page_params|
-            client.agents.list(repository_id: options[:repo], query: options[:query], **page_params)
+            client.agents.list(repository_id: resolve_repo(options[:repo]), query: options[:query], **page_params)
           end
           output_list(data, columns: [%w[ID id], %w[NAME name], %w[REPO github_repository_name],
                                       %w[ENABLED enabled], %w[SCHEDULE schedule]])
@@ -31,15 +31,12 @@ module SchwarmCli
 
       desc "create", "Create a repository agent"
       option :name, type: :string, required: true, desc: "Agent name"
-      option :repo, type: :string, required: true, desc: "Repository ID"
+      option :repo, type: :string, required: true, desc: "Repository ID, owner/repo, or GitHub URL"
       option :prompt, type: :string, required: true, desc: "Agent prompt"
       option :schedule, type: :string, desc: "Cron schedule"
       def create
         handle_errors do
-          attrs = { name: options[:name], github_repository_id: options[:repo], prompt: options[:prompt] }
-          attrs[:schedule] = options[:schedule] if options[:schedule]
-
-          data = client.agents.create(**attrs)
+          data = client.agents.create(**create_attrs)
           output_record(data, fields: { "ID" => "id", "Name" => "name", "Enabled" => "enabled" })
         end
       end
@@ -83,6 +80,15 @@ module SchwarmCli
 
       private
 
+      def create_attrs
+        attrs = {
+          name: options[:name], github_repository_id: resolve_repo(options[:repo]),
+          prompt: options[:prompt]
+        }
+        attrs[:schedule] = options[:schedule] if options[:schedule]
+        attrs
+      end
+
       def update_attrs
         {}.tap do |attrs|
           attrs[:name] = options[:name] if options[:name]

data/lib/schwarm_cli/commands/base.rb

@@ -25,6 +25,13 @@ module SchwarmCli
         @client ||= SchwarmCli::Client.new(url: options[:url], api_key: options[:token])
       end
 
+      # Resolves --repo input (ID, owner/repo, or GitHub URL) to a schwarm repo ID.
+      def resolve_repo(ref)
+        SchwarmCli::RepositoryResolver.new(client: client).resolve(ref)
+      rescue SchwarmCli::RepositoryResolver::ResolutionError => e
+        abort "Error: #{e.message}"
+      end
+
       def output_list(data, columns:)
         if options[:json]
           Formatters::Json.format(data)

data/lib/schwarm_cli/commands/recurring.rb

@@ -4,13 +4,13 @@ module SchwarmCli
   module Commands
     class Recurring < Base
       desc "list", "List recurring tasks"
-      option :repo, type: :string, desc: "Filter by repository ID"
+      option :repo, type: :string, desc: "Filter by repository ID, owner/repo, or GitHub URL"
       option :query, type: :string, desc: "Search by name"
       pagination_options
       def list
         handle_errors do
           data = fetch_paged do |page_params|
-            client.recurring.list(repository_id: options[:repo], query: options[:query], **page_params)
+            client.recurring.list(repository_id: resolve_repo(options[:repo]), query: options[:query], **page_params)
           end
           output_list(data, columns: [%w[ID id], %w[NAME name], %w[REPO github_repository_name],
                                       %w[ENABLED enabled], %w[SCHEDULE schedule]])
@@ -31,13 +31,13 @@ module SchwarmCli
 
       desc "create", "Create a recurring task"
       option :name, type: :string, required: true, desc: "Task name"
-      option :repo, type: :string, required: true, desc: "Repository ID"
+      option :repo, type: :string, required: true, desc: "Repository ID, owner/repo, or GitHub URL"
       option :prompt, type: :string, required: true, desc: "Task prompt"
       option :schedule, type: :string, required: true, desc: "Cron schedule"
       def create
         handle_errors do
           attrs = {
-            name: options[:name], github_repository_id: options[:repo],
+            name: options[:name], github_repository_id: resolve_repo(options[:repo]),
             prompt: options[:prompt], schedule: options[:schedule]
           }
 

data/lib/schwarm_cli/commands/repo_skills.rb

@@ -4,13 +4,15 @@ module SchwarmCli
   module Commands
     class RepoSkills < Base
       desc "list", "List repository-skill associations"
-      option :repo, type: :string, desc: "Filter by repository ID"
+      option :repo, type: :string, desc: "Filter by repository ID, owner/repo, or GitHub URL"
       option :skill, type: :string, desc: "Filter by skill ID"
       pagination_options
       def list
         handle_errors do
           data = fetch_paged do |page_params|
-            client.repo_skills.list(repository_id: options[:repo], skill_id: options[:skill], **page_params)
+            client.repo_skills.list(
+              repository_id: resolve_repo(options[:repo]), skill_id: options[:skill], **page_params
+            )
           end
           output_list(data, columns: [%w[ID id], %w[REPO github_repository_name],
                                       %w[SKILL skill_name]])
@@ -29,12 +31,12 @@ module SchwarmCli
       end
 
       desc "create", "Associate a skill with a repository"
-      option :repo, type: :string, required: true, desc: "Repository ID"
+      option :repo, type: :string, required: true, desc: "Repository ID, owner/repo, or GitHub URL"
       option :skill, type: :string, required: true, desc: "Skill ID"
       def create
         handle_errors do
           data = client.repo_skills.create(
-            github_repository_id: options[:repo], skill_id: options[:skill]
+            github_repository_id: resolve_repo(options[:repo]), skill_id: options[:skill]
           )
           output_record(data, fields: { "ID" => "id", "Repository" => "github_repository_id",
                                         "Skill" => "skill_id" })

data/lib/schwarm_cli/commands/secrets.rb

@@ -4,12 +4,12 @@ module SchwarmCli
   module Commands
     class Secrets < Base
       desc "list", "List secret files"
-      option :repo, type: :string, desc: "Filter by repository ID"
+      option :repo, type: :string, desc: "Filter by repository ID, owner/repo, or GitHub URL"
       pagination_options
       def list
         handle_errors do
           data = fetch_paged do |page_params|
-            client.secrets.list(repository_id: options[:repo], **page_params)
+            client.secrets.list(repository_id: resolve_repo(options[:repo]), **page_params)
           end
           output_list(data, columns: [%w[ID id], %w[NAME name], %w[REPO github_repository_name],
                                       %w[PATH path]])
@@ -29,14 +29,17 @@ module SchwarmCli
 
       desc "create", "Create a secret file"
       option :name, type: :string, required: true, desc: "Secret name"
-      option :repo, type: :string, required: true, desc: "Repository ID"
+      option :repo, type: :string, required: true, desc: "Repository ID, owner/repo, or GitHub URL"
       option :path, type: :string, required: true, desc: "File path in workspace"
       option :content, type: :string, desc: "Secret content"
       option :file, type: :string, desc: "Read content from file"
       def create
         handle_errors do
           content = read_content
-          attrs = { name: options[:name], github_repository_id: options[:repo], path: options[:path], content: }
+          attrs = {
+            name: options[:name], github_repository_id: resolve_repo(options[:repo]),
+            path: options[:path], content:
+          }
 
           data = client.secrets.create(**attrs)
           output_record(data, fields: { "ID" => "id", "Name" => "name", "Path" => "path" })

data/lib/schwarm_cli/commands/tasks.rb

@@ -5,7 +5,7 @@ module SchwarmCli
     class Tasks < Base
       desc "list", "List tasks (excludes archived by default)"
       option :status, type: :string, desc: "Filter by status"
-      option :repo, type: :string, desc: "Filter by repository ID"
+      option :repo, type: :string, desc: "Filter by repository ID, owner/repo, or GitHub URL"
       option :query, type: :string, desc: "Search by name"
       pagination_options
       def list
@@ -33,7 +33,7 @@ module SchwarmCli
       option :name, type: :string, required: true, desc: "Task name"
       option :prompt, type: :string, desc: "Task prompt"
       option :prompt_file, type: :string, desc: "Read prompt from file"
-      option :repo, type: :string, desc: "Repository ID"
+      option :repo, type: :string, desc: "Repository ID, owner/repo, or GitHub URL"
       option :status, type: :string, desc: "Initial status (draft/waiting)"
       option :template, type: :string, desc: "Template ID"
       option :depends_on, type: :array, desc: "Dependency task IDs"
@@ -48,7 +48,7 @@ module SchwarmCli
       option :name, type: :string, desc: "Task name"
       option :prompt, type: :string, desc: "Task prompt"
       option :prompt_file, type: :string, desc: "Read prompt from file"
-      option :repo, type: :string, desc: "Repository ID"
+      option :repo, type: :string, desc: "Repository ID, owner/repo, or GitHub URL"
       option :depends_on, type: :array, desc: "Dependency task IDs"
       def update(id)
         handle_errors do
@@ -117,7 +117,7 @@ module SchwarmCli
       desc "handoff", "Hand off the current local branch to schwarm as a ready task"
       option :prompt, type: :string, desc: "Task prompt"
       option :prompt_file, type: :string, desc: "Read prompt from file"
-      option :repo, type: :string, desc: "Repository ID (skips origin auto-detect)"
+      option :repo, type: :string, desc: "Repository ID, owner/repo, or GitHub URL (skips origin auto-detect)"
       option :name, type: :string, desc: "Task name (defaults to the branch name)"
       def handoff
         prompt = read_prompt
@@ -125,7 +125,7 @@ module SchwarmCli
 
         handle_errors do
           result = SchwarmCli::HandsOffTask.new(client: client).call(
-            prompt: prompt, repo_override: options[:repo], name_override: options[:name]
+            prompt: prompt, repo_override: resolve_repo(options[:repo]), name_override: options[:name]
           )
           print_handoff_result(result)
         end
@@ -136,7 +136,7 @@ module SchwarmCli
       def list_attrs
         exclude_archived = options[:status].nil? && !options[:all]
         {
-          status: options[:status], repository_id: options[:repo], query: options[:query],
+          status: options[:status], repository_id: resolve_repo(options[:repo]), query: options[:query],
           archived: exclude_archived ? false : nil
         }
       end
@@ -154,14 +154,14 @@ module SchwarmCli
       def create_attrs
         {
           name: options[:name], prompt: read_prompt,
-          github_repository_id: options[:repo], status: options[:status],
+          github_repository_id: resolve_repo(options[:repo]), status: options[:status],
           task_template_id: options[:template], dependency_ids: options[:depends_on]
         }.compact
       end
 
       def update_attrs
         {
-          name: options[:name], github_repository_id: options[:repo],
+          name: options[:name], github_repository_id: resolve_repo(options[:repo]),
           dependency_ids: options[:depends_on]
         }.compact.tap do |attrs|
           attrs[:prompt] = read_prompt if options[:prompt] || options[:prompt_file]

data/lib/schwarm_cli/hands_off_task.rb

@@ -84,28 +84,17 @@ module SchwarmCli
     end
 
     def resolve_repository(origin:, override:)
-      if override
-        begin
-          return @client.repositories.find(override)["data"]
-        rescue Faraday::ResourceNotFound
-          return nil
-        end
-      end
-
-      slug = origin_slug(origin)
-      response = @client.repositories.list(query: slug)
-      Array(response["data"]).find { |r| normalize_url(r["github_url"]) == normalize_url(origin) }
-    end
+      return find_by_id(override) if override
 
-    def origin_slug(url)
-      # Accept both https://github.com/org/repo[.git] and git@github.com:org/repo.git
-      url.sub(%r{\Ahttps?://github\.com/}, "").sub(/\Agit@github\.com:/, "").sub(/\.git\z/, "")
+      RepositoryResolver.new(client: @client).resolve_record(origin)
+    rescue RepositoryResolver::ResolutionError
+      nil
     end
 
-    def normalize_url(url)
-      return nil if url.nil?
-
-      url.sub(/\.git\z/, "").sub(/\Agit@github\.com:/, "https://github.com/")
+    def find_by_id(id)
+      @client.repositories.find(id)["data"]
+    rescue Faraday::ResourceNotFound
+      nil
     end
 
     def create_task(repo:, branch:, prompt:, name_override:)

data/lib/schwarm_cli/repository_resolver.rb

@@ -0,0 +1,65 @@
+# frozen_string_literal: true
+
+module SchwarmCli
+  # Turns a user-provided `--repo` reference into a schwarm repository ID.
+  #
+  # Accepted inputs:
+  #   - a schwarm repository ID (returned as-is)
+  #   - "owner/repo"
+  #   - "https://github.com/owner/repo[.git]"
+  #   - "git@github.com:owner/repo[.git]"
+  class RepositoryResolver
+    class ResolutionError < StandardError; end
+
+    SLUG_PATTERNS = [
+      %r{\Ahttps?://github\.com/([^/\s]+/[^/\s]+?)(?:\.git)?/?\z},
+      %r{\Agit@github\.com:([^/\s:]+/[^/\s:]+?)(?:\.git)?\z},
+      %r{\A([^/\s:]+/[^/\s:]+?)(?:\.git)?\z}
+    ].freeze
+
+    def initialize(client:)
+      @client = client
+    end
+
+    def resolve(ref)
+      return nil if blank?(ref)
+
+      record = resolve_record(ref)
+      record ? record["id"] : ref
+    end
+
+    # Like `resolve`, but returns the full repo record when the ref is looked up
+    # via slug/URL. Returns nil when `ref` is blank or already a bare ID (caller
+    # should `find` by id directly in that case).
+    def resolve_record(ref)
+      return nil if blank?(ref)
+
+      slug = extract_slug(ref.strip)
+      slug ? lookup_by_slug(slug, ref) : nil
+    end
+
+    private
+
+    def blank?(ref)
+      ref.nil? || ref.to_s.strip.empty?
+    end
+
+    def extract_slug(ref)
+      SLUG_PATTERNS.filter_map { |pat| ref.match(pat)&.[](1) }.first
+    end
+
+    def lookup_by_slug(slug, original)
+      response = @client.repositories.list(query: slug)
+      match = Array(response["data"]).find { |r| slug_from_url(r["url"]) == slug }
+      raise ResolutionError, "no schwarm repository matches `#{original}`" if match.nil?
+
+      match
+    end
+
+    def slug_from_url(url)
+      return nil if url.nil?
+
+      url.sub(%r{\Ahttps?://github\.com/}, "").sub(/\Agit@github\.com:/, "").sub(/\.git\z/, "")
+    end
+  end
+end

data/lib/schwarm_cli/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module SchwarmCli
-  VERSION = "0.1.2"
+  VERSION = "0.1.4"
 end

data/lib/schwarm_cli.rb

@@ -4,6 +4,7 @@ require_relative "schwarm_cli/version"
 require_relative "schwarm_cli/config"
 require_relative "schwarm_cli/client"
 require_relative "schwarm_cli/git"
+require_relative "schwarm_cli/repository_resolver"
 require_relative "schwarm_cli/hands_off_task"
 require_relative "schwarm_cli/formatters/json"
 require_relative "schwarm_cli/formatters/table"

data/schwarm-skill.md

@@ -97,8 +97,9 @@ Tasks left as `draft` will never run.
 **When:** You've dispatched tasks and want to check on them.
 
 **Steps:**
-1. List active tasks:
+1. List active tasks (archived excluded by default):
    ```bash
+   schwarm tasks list
    schwarm tasks list --status claimed
    schwarm tasks list --status ready
    schwarm tasks list --status error
@@ -224,3 +225,11 @@ for tasks in a repository.
 - When building a DAG, create all tasks as drafts first, then start them all.
 - For long prompts, write them to a file and use `--prompt-file`.
 - Run `schwarm <command> help` for full flag documentation on any command.
+- `schwarm tasks list` excludes archived tasks by default. Use `--all` to
+  include them or `--status archived` to see only archived.
+- `schwarm sessions list` shows only active sessions (pending/running) by
+  default. Use `--all` to include terminal states.
+- All list commands support `--limit N` and `--page N` for pagination. The
+  footer shows "showing N of M · page X of Y".
+- Run `schwarm skill` to print this document — useful for piping into context
+  or refreshing your knowledge of the available workflows.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: schwarm-cli
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.4
 platform: ruby
 authors:
 - Vincent Garrigues
@@ -86,6 +86,7 @@ executables:
 extensions: []
 extra_rdoc_files: []
 files:
+- README.md
 - bin/schwarm
 - lib/schwarm_cli.rb
 - lib/schwarm_cli/client.rb
@@ -121,6 +122,7 @@ files:
 - lib/schwarm_cli/formatters/table.rb
 - lib/schwarm_cli/git.rb
 - lib/schwarm_cli/hands_off_task.rb
+- lib/schwarm_cli/repository_resolver.rb
 - lib/schwarm_cli/version.rb
 - schwarm-skill.md
 homepage: https://github.com/getdexter/schwarm