Merge pull request #12 from osodevops/codex/cli-agent-project-workflows

Add agent project workflows to CLI

Author: sionsmith

CHANGELOG.md

@@ -5,6 +5,18 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/),
 and this project adheres to [Semantic Versioning](https://semver.org/).
 
+## [0.1.4] - 2026-05-12
+
+### Added
+
+- Client discovery and creation commands for agent setup workflows.
+- Project creation from the CLI, including client filtering, billable defaults, explicit task IDs, and conflict handling.
+- Agent session recording fields for source metadata, duration-based logging, and setup wizard support.
+
+### Fixed
+
+- Integration tests now write mock config to the Windows `%APPDATA%` path as well as Unix/macOS paths.
+
 ## [0.1.3] - 2026-05-05
 
 ### Added

Cargo.lock

@@ -1,6 +1,6 @@
 [package]
 name = "keito-cli"
-version = "0.1.3"
+version = "0.1.4"
 edition = "2021"
 description = "CLI for AI agents and humans to track billable time against the Keito platform"
 license = "MIT"

Cargo.toml

@@ -128,6 +128,7 @@ Configuration file:
 api_key = "kto_..."
 account_id = "co_abc123"
 workspace_id = "co_abc123" # legacy alias, kept for compatibility
+api_url = "https://app.keito.ai"
 ```
 
 ### Credential Precedence
@@ -150,6 +151,7 @@ Find the Company ID in Keito under Settings > API & Developers > Company ID.
 | Variable | Description |
 |---|---|
 | `KEITO_API_KEY` | API key — takes precedence over config |
+| `KEITO_API_URL` | API base URL override; defaults to `https://app.keito.ai` |
 | `KEITO_ACCOUNT_ID` | Company/account ID sent as `Keito-Account-Id` |
 | `KEITO_WORKSPACE_ID` | Legacy alias for `KEITO_ACCOUNT_ID` |
 

README.md

@@ -1,6 +1,6 @@
 use chrono::Utc;
 use reqwest::header::{HeaderMap, HeaderValue, AUTHORIZATION};
-use reqwest::Client;
+use reqwest::Client as HttpClient;
 use std::time::Duration;
 
 use crate::api::error::map_status_to_error;
@@ -9,7 +9,7 @@ use crate::config::ResolvedAuth;
 use crate::error::AppError;
 
 pub struct KeitorClient {
-    client: Client,
+    client: HttpClient,
     base_url: String,
 }
 
@@ -27,7 +27,7 @@ impl KeitorClient {
                 .map_err(|_| AppError::Auth("Invalid workspace ID format".into()))?,
         );
 
-        let client = Client::builder()
+        let client = HttpClient::builder()
             .default_headers(headers.clone())
             .timeout(Duration::from_secs(30))
             .build()
@@ -146,24 +146,63 @@ impl KeitorClient {
             .await
     }
 
+    pub async fn list_clients(&self) -> Result<Vec<Client>, AppError> {
+        let path = path_with_query(
+            "/api/v2/clients",
+            &[("is_active", "true"), ("per_page", "200")],
+        );
+        let resp: ClientsResponse = self
+            .request_with_retry(reqwest::Method::GET, &path, None::<&()>)
+            .await?;
+        Ok(resp.clients)
+    }
+
+    pub async fn create_client(&self, req: &CreateClientRequest) -> Result<Client, AppError> {
+        self.request_with_retry(reqwest::Method::POST, "/api/v2/clients", Some(req))
+            .await
+    }
+
     pub async fn list_projects(&self) -> Result<Vec<Project>, AppError> {
-        let resp: ProjectsResponse = self
-            .request_with_retry(
-                reqwest::Method::GET,
-                "/api/v2/projects?is_active=true&per_page=200",
-                None::<&()>,
+        self.list_projects_for_client(None).await
+    }
+
+    pub async fn list_projects_for_client(
+        &self,
+        client_id: Option<&str>,
+    ) -> Result<Vec<Project>, AppError> {
+        let path = if let Some(client_id) = client_id {
+            path_with_query(
+                "/api/v2/projects",
+                &[
+                    ("is_active", "true"),
+                    ("per_page", "200"),
+                    ("client_id", client_id),
+                ],
+            )
+        } else {
+            path_with_query(
+                "/api/v2/projects",
+                &[("is_active", "true"), ("per_page", "200")],
             )
+        };
+        let resp: ProjectsResponse = self
+            .request_with_retry(reqwest::Method::GET, &path, None::<&()>)
             .await?;
         Ok(resp.projects)
     }
 
+    pub async fn create_project(&self, req: &CreateProjectRequest) -> Result<Project, AppError> {
+        self.request_with_retry(reqwest::Method::POST, "/api/v2/projects", Some(req))
+            .await
+    }
+
     pub async fn list_tasks(&self) -> Result<Vec<Task>, AppError> {
+        let path = path_with_query(
+            "/api/v2/tasks",
+            &[("is_active", "true"), ("per_page", "200")],
+        );
         let resp: TasksResponse = self
-            .request_with_retry(
-                reqwest::Method::GET,
-                "/api/v2/tasks?is_active=true&per_page=200",
-                None::<&()>,
-            )
+            .request_with_retry(reqwest::Method::GET, &path, None::<&()>)
             .await?;
         Ok(resp.tasks)
     }
@@ -276,6 +315,8 @@ impl KeitorClient {
                 }),
                 billable: Some(timer.billable),
                 is_running: false,
+                started_time: timer.started_time.clone(),
+                ended_time: timer.ended_time.clone(),
                 source: Some("cli".into()),
                 metadata: timer.metadata.clone(),
             })
@@ -295,6 +336,16 @@ impl KeitorClient {
     }
 }
 
+fn path_with_query(path: &str, query: &[(&str, &str)]) -> String {
+    let url = reqwest::Url::parse_with_params(&format!("https://keito.local{path}"), query)
+        .expect("static API path should be a valid URL");
+
+    match url.query() {
+        Some(query) => format!("{}?{}", url.path(), query),
+        None => url.path().to_string(),
+    }
+}
+
 fn is_missing_stop_route(err: &AppError) -> bool {
     matches!(
         err,

src/api/client.rs

@@ -47,6 +47,33 @@ impl MeResponse {
     }
 }
 
+// -- Clients --
+
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct Client {
+    pub id: String,
+    pub name: String,
+    #[serde(default)]
+    pub currency: Option<String>,
+    #[serde(default)]
+    pub address: Option<String>,
+    #[serde(default)]
+    pub is_active: bool,
+    #[serde(default)]
+    pub created_at: Option<DateTime<Utc>>,
+    #[serde(default)]
+    pub updated_at: Option<DateTime<Utc>>,
+}
+
+#[derive(Debug, Serialize)]
+pub struct CreateClientRequest {
+    pub name: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub address: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub currency: Option<String>,
+}
+
 // -- Projects --
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -83,6 +110,24 @@ impl Project {
     }
 }
 
+#[derive(Debug, Serialize)]
+pub struct CreateProjectRequest {
+    pub client_id: String,
+    pub name: String,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub code: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub notes: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub is_billable: Option<bool>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub bill_by: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub budget_by: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub task_ids: Option<Vec<String>>,
+}
+
 // -- Tasks --
 
 #[derive(Debug, Clone, Serialize, Deserialize)]
@@ -181,6 +226,10 @@ pub struct CreateTimeEntryRequest {
     pub billable: Option<bool>,
     pub is_running: bool,
     #[serde(skip_serializing_if = "Option::is_none")]
+    pub started_time: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ended_time: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub source: Option<String>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub metadata: Option<serde_json::Value>,
@@ -189,6 +238,12 @@ pub struct CreateTimeEntryRequest {
 #[derive(Debug, Serialize)]
 #[allow(dead_code)]
 pub struct UpdateTimeEntryRequest {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub project_id: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub task_id: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub spent_date: Option<String>,
     #[serde(skip_serializing_if = "Option::is_none")]
     pub is_running: Option<bool>,
     #[serde(skip_serializing_if = "Option::is_none")]
@@ -198,6 +253,10 @@ pub struct UpdateTimeEntryRequest {
     #[serde(skip_serializing_if = "Option::is_none")]
     pub billable: Option<bool>,
     #[serde(skip_serializing_if = "Option::is_none")]
+    pub started_time: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    pub ended_time: Option<String>,
+    #[serde(skip_serializing_if = "Option::is_none")]
     pub metadata: Option<serde_json::Value>,
 }
 
@@ -233,6 +292,21 @@ pub struct ProjectsResponse {
     pub links: Option<PaginationLinks>,
 }
 
+#[derive(Debug, Clone, Serialize, Deserialize)]
+pub struct ClientsResponse {
+    pub clients: Vec<Client>,
+    #[serde(default)]
+    pub per_page: Option<u64>,
+    #[serde(default)]
+    pub total_pages: Option<u64>,
+    #[serde(default)]
+    pub total_entries: Option<u64>,
+    #[serde(default)]
+    pub page: Option<u64>,
+    #[serde(default)]
+    pub links: Option<PaginationLinks>,
+}
+
 #[derive(Debug, Clone, Serialize, Deserialize)]
 pub struct TasksResponse {
     pub tasks: Vec<Task>,
@@ -297,13 +371,17 @@ mod tests {
             notes: Some("test".into()),
             billable: Some(true),
             is_running: false,
+            started_time: Some("09:00".into()),
+            ended_time: Some("10:30".into()),
             source: Some("cli".into()),
             metadata: None,
         };
 
         let value = serde_json::to_value(req).unwrap();
         assert_eq!(value["spent_date"], "2026-03-04");
         assert_eq!(value["billable"], true);
+        assert_eq!(value["started_time"], "09:00");
+        assert_eq!(value["ended_time"], "10:30");
         assert!(value.get("date").is_none());
         assert!(value.get("is_billable").is_none());
     }

src/api/models.rs

@@ -0,0 +1,52 @@
+use clap::{Args, Subcommand};
+
+#[derive(Args)]
+pub struct ClientsCommand {
+    #[command(subcommand)]
+    pub command: ClientsSubcommand,
+}
+
+#[derive(Subcommand)]
+pub enum ClientsSubcommand {
+    /// List active clients
+    #[command(long_about = "\
+List active clients available to the authenticated Keito account.
+
+Use this before project discovery when an agent needs to map user-provided \
+client context to Keito's project names and IDs.
+
+API EFFECT:
+  GET /api/v2/clients?is_active=true&per_page=200
+
+EXAMPLE:
+  keito clients list --json")]
+    List {
+        /// Max clients to display
+        #[arg(long)]
+        limit: Option<usize>,
+    },
+
+    /// Create a client
+    #[command(long_about = "\
+Create a client in Keito.
+
+Requires a Keito API key with manager permissions.
+
+API EFFECT:
+  POST /api/v2/clients
+
+EXAMPLE:
+  keito clients create \"Acme Ltd\" --currency GBP --json")]
+    Create {
+        /// Client name
+        name: String,
+
+        /// Client billing currency, such as USD or GBP
+        #[arg(long)]
+        currency: Option<String>,
+
+        /// Client postal address
+        #[arg(long)]
+        address: Option<String>,
+    },
+}

src/cli/clients.rs

@@ -1,4 +1,5 @@
 pub mod auth;
+pub mod clients;
 pub mod projects;
 pub mod time;
 
@@ -19,6 +20,7 @@ and returns structured exit codes for programmatic error handling.",
     after_long_help = "\
 ENVIRONMENT VARIABLES:
   KEITO_API_KEY          API key (takes precedence over config)
+  KEITO_API_URL          API base URL override
   KEITO_ACCOUNT_ID       Company/account ID for Keito-Account-Id
   KEITO_WORKSPACE_ID     Legacy alias for KEITO_ACCOUNT_ID
 
@@ -92,9 +94,12 @@ this value in Keito under Settings > API & Developers > Company ID."
 }
 
 #[derive(Subcommand)]
+#[allow(clippy::large_enum_variant)]
 pub enum Command {
     /// Manage authentication (login, logout, status, whoami)
     Auth(auth::AuthCommand),
+    /// Browse clients
+    Clients(clients::ClientsCommand),
     /// Track time entries (start, stop, log, list, running)
     Time(time::TimeCommand),
     /// Browse projects and tasks