@4ge/cli 0.2.3 → 0.2.5

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (12) hide show
  1. package/README.md +117 -184
  2. package/dist/base.js +8 -3
  3. package/dist/commands/epic/list.js +1 -1
  4. package/dist/commands/feature/list.js +1 -1
  5. package/dist/commands/flow/list.js +1 -1
  6. package/dist/commands/idea/graduate.js +3 -2
  7. package/dist/commands/project/list.js +1 -1
  8. package/dist/commands/story/list.js +1 -1
  9. package/dist/commands/template/pull.js +1 -1
  10. package/package.json +3 -3
  11. package/skills/4ge-cli.md +23 -23
  12. package/usage.md +4 -2
package/README.md CHANGED
@@ -1,228 +1,161 @@
1
- # 4ge-CLI: A Universal Interface for 4ge Resources
1
+ # 4ge CLI
2
2
 
3
- The official Command Line Interface and API Bridge for the 4ge Service Architecture.
3
+ [![npm version](https://img.shields.io/npm/v/@4ge/cli.svg)](https://www.npmjs.com/package/@4ge/cli)
4
+ [![license](https://img.shields.io/npm/l/@4ge/cli.svg)](./LICENSE)
4
5
 
5
- This CLI is designed with a **Dual-Output Architecture**: it provides a rich, interactive Terminal User Interface (TUI) for human developers and a strict, deterministic JSON output stream for AI Agents.
6
+ The official command-line interface for [4ge](https://4ge.dev) - _“Architect at the
7
+ Speed of Thought.”_ The visual workspace that validates what to build, before you
8
+ build it.
6
9
 
7
- ## Project Overview
10
+ 4ge structures your plans into roadmaps, epics, stories, features, ideas, and
11
+ templates - with acceptance criteria so you know it’s done right. The `4ge` CLI
12
+ brings that workspace to your terminal and to your AI agents: one tool with two
13
+ faces, a rich terminal UI for humans and a strict, deterministic JSON stream for
14
+ machines.
8
15
 
9
- **Problem Statement:**
10
- Developing and automating workflows within the 4ge ecosystem presents a dual challenge:
11
- 1. **For Human Developers:** Interacting with complex APIs often involves fragmented tools, manual data parsing, and a steep learning curve to translate service mesh logic into actionable insights. This leads to inefficient debugging, inconsistent context, and slower development cycles when trying to understand project states or access artifacts locally.
12
- 2. **For AI Agents:** Automating tasks against APIs demands highly reliable, deterministic, and self-validating interfaces. Traditional command-line tools, primarily designed for human readability, frequently produce inconsistent outputs, lack robust error handling, and can easily break fragile automation scripts. This hinders the development of dependable, AI-driven workflows.
16
+ - 👉 **Marketing site & product**: <https://4ge.dev>
17
+ - 📖 **Full usage guide**: [`usage.md`](./usage.md)
18
+ - 💬 **Issues & feedback**: [GitHub Issues](https://github.com/Conflate-AI/4ge-cli/issues)
13
19
 
14
- Both human developers and AI agents currently lack a unified, secure, and context-aware local interface that caters specifically to their distinct interaction needs, forcing compromises between usability and automation reliability.
20
+ ---
15
21
 
16
- **Solution: The 4ge-CLI**
17
- The 4ge-CLI is designed as the definitive local interface for the 4ge ecosystem, bridging the gap between powerful 4ge APIs and diverse user environments. It provides a robust, intuitive, and secure command-line experience specifically engineered for both high-fidelity human interaction and seamless, error-proof AI Agent orchestration.
22
+ ## Install
18
23
 
19
- **Core Vision:**
20
- To be the primary external gateway to 4ge resources, the 4ge-CLI translates the intricate 4ge service mesh into an intuitive, nested command structure. Its innovative "Dual-Output" strategy ensures optimal experiences: human developers benefit from a rich, interactive Terminal User Interface (TUI), while AI agents receive a consistently structured, schema-validated JSON stream, guaranteeing reliability for automated processes.
21
-
22
- **Key Personas:**
23
-
24
- * **The Developer (Human):**
25
- * **Description:** An engineer, product manager, or data scientist who interacts directly with 4ge resources.
26
- * **Goals:** Quickly understand the state of their 4ge workspace, projects, and artifacts; efficiently troubleshoot issues; explore 4ge resources with minimal friction; and securely manage local configuration and credentials.
27
- * **Motivations:** Desires a visually appealing and interactive TUI that offers immediate feedback, guided exploration, and clear status updates, reducing cognitive load and accelerating workflow. They want to avoid manual API calls or cumbersome web interfaces for routine information retrieval.
28
- * **CLI Value:** Provides a rich, color-coded TUI with interactive prompts, progress indicators, and easily navigable tables, making complex data digestible and interaction intuitive.
29
-
30
- * **The AI Agent (Machine):**
31
- * **Description:** An automated script, bot, or intelligent agent designed to interact with 4ge APIs programmatically. This includes CI/CD pipelines, custom automation scripts, or advanced AI-driven workflow engines.
32
- * **Goals:** Execute commands deterministically, receive predictable and machine-readable outputs, ensure zero-error execution loops, and securely authenticate without human intervention.
33
- * **Motivations:** Requires absolute reliability and consistency to build resilient automation. Any deviation in output format or unexpected errors can halt critical operations. They need strict validation and clear error reporting to maintain continuous operation.
34
- * **CLI Value:** Offers a `--json` output flag that returns strictly schema-validated JSON, leveraging Zod for contract enforcement. Supports headless authentication via API keys, robust error tracing, and "Action Hints" to guide subsequent automated commands, enabling highly reliable and autonomous operations.
35
-
36
- **Core Capabilities & Functional Highlights:**
37
-
38
- The 4ge-CLI is built upon a foundation designed for reliability, security, and developer efficiency:
39
-
40
- 1. **Unified Gateway Communication:** Acts as a thin client, delegating business logic to the 4ge Core API. It intelligently signals `X-Client-Type: 4ge-agent` for machine interactions and processes "Action Hints" for guided automation.
41
- 2. **Secure Local State Management:** Manages non-sensitive configuration in `.4ge/config.yaml` (e.g., `project_id`, `environment`) and securely stores sensitive credentials (JWTs, Refresh Tokens, API Keys) in the user's home directory (`~/.4ge/credentials.json`) to prevent accidental exposure.
42
- 3. **Flexible Authentication & Identity:** Supports PKCE-based OAuth for interactive human login and `4GE_API_KEY` (Personal Access Tokens) for seamless headless authentication in automated environments. Commands inherently respect user permissions via Supabase RLS policies.
43
- 4. **Context-Aware Operations:** The `4ge init` command establishes a local `.4ge/config.yaml`, anchoring the CLI to a specific project. Subsequent commands automatically leverage this local context, eliminating redundant flag usage and providing folder-specific information.
44
- 5. **Schema-Driven Reliability:** Employs a "Contract-First" approach, where internal Zod schemas mirror Core API definitions. This ensures robust input validation and response parsing, providing detailed error traces for agents and user-friendly "Update Required" messages for humans in case of schema mismatches.
45
- 6. **Three-Tier Output Design (UX):**
46
- * **Pretty Mode (Default):** Ink-rendered styled output — color-coded tables, detail views, spinners, and success/error feedback. No follow-up prompts. Command runs, shows result, exits.
47
- * **Interactive Mode (`--interactive` / `-i`):** Everything in Pretty, plus action-hint navigation menus, follow-up command suggestions, and prompts for missing values. Configurable as default via `cli.default_mode: interactive` in `.4ge/config.yaml`.
48
- * **Machine Mode (`--json`):** Strict `{ "data": T, "error": null, "metadata": {...} }` JSON envelope. No Ink, no prompts, no colors. Fully deterministic for AI agents.
49
-
50
- **Mode Resolution:** `--interactive`/`--no-interactive` flag → `cli.default_mode` config → `pretty` (hard default)
51
-
52
- > **Note for Contributors**: When implementing new commands, always extract the inner `.data` from SDK responses before passing to `outputJson()`. See the [Technical Specification](docs/technical-specification.md#-outputjson-double-nesting-anti-pattern) for details.
53
- 7. **Foundational Integration Features (MVP):** Enables read-only inspection of active 4ge resources, fetching specific project details, and loading artifact statuses and the artifacts themselves. Future enhancements include resource management (scaffolding) and syncing capabilities.
54
- 8. **Enhanced Safety & Validation:** Supports `--dry-run` for previewing changes, crucial for automated workflows. Comprehensive Zod schema validation for all command inputs and API responses prevents "state-drift" and ensures data integrity.
55
-
56
- -----
57
-
58
- ## 🏗 Architecture & Stack
59
-
60
- - **Runtime:** Node.js 24.x (LTS)
61
- - **Package Manager:** pnpm
62
- - **Framework:** [oclif v4](https://oclif.io/) (Nested Command Structure)
63
- - **UI (Human):** [Ink](https://github.com/vadimdemedes/ink) (React-based terminal rendering)
64
- - **UI (Machine):** Standardized `--json` flag output
65
- - **API Sync:** `@hey-api/openapi-ts` (Contract-driven Zod schema and TypeScript generation)
66
- - **State Management:** Local `.4ge/config.yaml`
67
-
68
-
69
- ## 🛠 TUI Mode Configuration
70
-
71
- The 4ge-CLI provides three output modes, configurable per-command or as a project default:
72
-
73
- | Mode | Trigger | Behavior |
74
- |------|---------|----------|
75
- | **Pretty** | Default (no flags) | Styled Ink output (tables, spinners, colors). No follow-up prompts. |
76
- | **Interactive** | `--interactive` / `-i` | Pretty output + action-hint menus, follow-up suggestions, selection prompts. |
77
- | **Machine** | `--json` / `-j` | Strict JSON envelope. No TUI, no prompts, no colors. Fully deterministic for AI agents. |
78
-
79
- ### Setting the Default Mode
80
-
81
- To make interactive mode the default for a project:
24
+ Requires **Node.js v24+**. The package ships prebuilt - no build step on your machine.
82
25
 
83
26
  ```bash
84
- 4ge config:set cli.default_mode interactive
85
- ```
86
-
87
- This writes to `.4ge/config.yaml`:
88
- ```yaml
89
- cli:
90
- default_mode: interactive
27
+ npm install -g @4ge/cli
28
+ 4ge --help
91
29
  ```
92
30
 
93
- ### Resolution Order
31
+ Update later:
94
32
 
95
- When running a command, the mode is resolved as:
96
- 1. `--interactive` flag → forced interactive
97
- 2. `--no-interactive` flag → forced pretty (overrides config)
98
- 3. `cli.default_mode` in `.4ge/config.yaml` → uses config value
99
- 4. *(fallback)* → pretty mode
100
-
101
- **Note:** `4ge init` is always interactive regardless of mode settings — it's an inherently interactive setup flow.
33
+ ```bash
34
+ npm update -g @4ge/cli
35
+ ```
102
36
 
103
- ### Examples
37
+ ## Quick start
104
38
 
105
39
  ```bash
106
- # Pretty mode — styled table, no prompts
107
- 4ge project:list
40
+ # 1. Authenticate with a Personal Access Token
41
+ 4ge auth:login --token <your_api_key>
108
42
 
109
- # Interactive mode — table + select an item + action hints
110
- 4ge project:list --interactive
43
+ # 2. Anchor the CLI to a 4ge project (interactive)
44
+ 4ge init
111
45
 
112
- # Override config back to pretty
113
- 4ge project:list --no-interactive
46
+ # 3. Confirm who you are
47
+ 4ge whoami
114
48
 
115
- # Machine mode — strict JSON
116
- 4ge project:list --json
49
+ # 4. List your projects
50
+ 4ge project:list
117
51
  ```
118
52
 
119
- ## 🚀 Prerequisites
53
+ You can get a Personal Access Token from your 4ge workspace at <https://4ge.dev>.
120
54
 
121
- **End users:** Node.js v24+ (git + GitHub SSH key for private install).
55
+ Authentication can also be provided headlessly via the `4GE_API_KEY` environment
56
+ variable (ideal for CI/CD and AI agents).
122
57
 
123
- **Contributors:** Node.js v24+, pnpm v9+.
58
+ ## Output modes
124
59
 
60
+ Every command supports three interchangeable output modes:
125
61
 
126
- ## 🛠 Getting Started
62
+ | Mode | Trigger | Behaviour |
63
+ |------|---------|-----------|
64
+ | **Pretty** | _default_ | Styled terminal output - tables, detail views, spinners. No follow-up prompts. |
65
+ | **Interactive** | `--interactive` / `-i` | Pretty output + action-hint menus, follow-up suggestions, and selection prompts. |
66
+ | **Machine** | `--json` / `-j` | Strict JSON envelope. No TUI, no prompts, no colours. Deterministic for AI agents. |
127
67
 
128
- ### End users (install from npm)
68
+ Resolution order: `--interactive`/`--no-interactive` flag → `cli.default_mode` in
69
+ `.4ge/config.yaml` → `pretty` (hard default).
129
70
 
130
71
  ```bash
131
- npm install -g @4ge/cli
132
- 4ge --help
133
- ```
134
-
135
- Requires Node.js 24+ (no git, no SSH key needed). The package ships prebuilt
136
- — no build step on your machine. Update later with `npm update -g @4ge/cli`.
137
-
138
- ### Contributors (from source)
72
+ # Pretty - styled table
73
+ 4ge project:list
139
74
 
140
- 1. **Clone and Install:**
75
+ # Interactive - table + navigate + action hints
76
+ 4ge project:list --interactive
141
77
 
142
- ```bash
143
- git clone git@github.com:Conflate-AI/4ge-cli.git
144
- cd 4ge-cli
145
- pnpm install
78
+ # Machine - strict JSON envelope
79
+ 4ge project:list --json
146
80
  ```
147
81
 
148
- 2. **Sync the Core API Contract:**
149
- The 4ge-CLI uses a "Contract-First" approach. It does not define its own data models. Before running or building the CLI, you must sync the Zod schemas and API clients from the Core API's OpenAPI specification.
150
- *Ensure the 4ge Core API is running locally or accessible via the URL in `openapi-ts.config.ts`, then run:*
82
+ The JSON envelope returned by `--json` mode is always:
151
83
 
152
- ```bash
153
- pnpm sync-api
84
+ ```json
85
+ {
86
+ "data": { "...": "..." },
87
+ "error": null,
88
+ "metadata": { "timestamp": "2026-05-23T10:00:00.000Z" }
89
+ }
154
90
  ```
155
91
 
156
- *This will populate the `src/generated/api` directory.*
92
+ See [`usage.md`](./usage.md) → “JSON Mode” for the full error envelope and error codes.
157
93
 
94
+ ## AI agent integration
158
95
 
159
- 3. **Run Locally:**
96
+ This CLI is a first-class tool for 4ge AI agents. Agents interact through the same
97
+ commands, but append `--json` for deterministic, validated output:
160
98
 
161
- ```bash
162
- pnpm dev --help
163
- ```
99
+ - **Always** pass `--json` - disables prompts, returns a schema-validated envelope.
100
+ - Authenticate headlessly with the `4GE_API_KEY` environment variable.
101
+ - The CLI automatically sends `X-Client-Type: 4ge-agent` to the 4ge API.
164
102
 
165
- 4. **Authenticate:**
166
- ```bash
167
- 4ge auth:login --token <api_key> # installed
168
- # or, in dev:
169
- pnpm dev auth:login --token <api_key>
170
- ```
103
+ ### Install the agent skill
104
+
105
+ Teach an AI agent (pi, Cursor, Claude Code, Codex, Gemini CLI, GitHub Copilot,
106
+ OpenCode, …) how to use the CLI by installing the bundled skill document:
171
107
 
172
- 5. **Initialize a Project:**
173
108
  ```bash
174
- 4ge init # offers to install the agent skill (default: No)
175
- ```
109
+ # Universal project scope -> .agents/skills/4ge-cli/SKILL.md
110
+ 4ge skill:install
176
111
 
177
- ## 📂 Repository Structure
112
+ # Target a specific harness
113
+ 4ge skill:install --agent pi # -> .pi/skills/4ge-cli/SKILL.md
114
+ 4ge skill:install --agent claude-code # -> .claude/skills/4ge-cli/SKILL.md
178
115
 
116
+ # User (global) scope, or overwrite an existing install
117
+ 4ge skill:install --global
118
+ 4ge skill:install --force
179
119
  ```
180
- .
181
- ├── bin/ # Executable entry points (run.js, dev.js)
182
- ├── src/
183
- │ ├── base.ts # BaseCommand with --json flag support
184
- │ ├── commands/ # oclif command implementations
185
- │ │ ├── index.ts # Root command (help)
186
- │ │ ├── init.ts # 4ge init
187
- │ │ ├── login.ts # 4ge login (alias)
188
- │ │ ├── whoami.ts # 4ge whoami (alias)
189
- │ │ └── auth/ # 4ge auth:login | auth:logout | auth:status | auth:profile:use
190
- │ ├── core/ # Business logic (framework-agnostic)
191
- │ │ ├── auth/ # Credential storage, resolution, API client
192
- │ │ ├── config/ # .4ge/config.yaml parser, Zod schema
193
- │ │ ├── skill/ # Agent skill path resolution + installer
194
- │ │ └── api/ # Response extraction, validation, retry
195
- │ ├── generated/ # ⚠️ DO NOT EDIT: Auto-generated from Core API
196
- │ └── ui/ # Ink React components (TUI)
197
- │ ├── components/ # Spinner, DataTable, DetailView, SelectPrompt, ConfirmPrompt, etc.
198
- │ ├── hooks/ # useActionHints hook
199
- │ ├── prompt-helpers.tsx # Ink-based interactive prompt renderers
200
- │ └── render.ts # renderTui() helper
201
- ├── skills/ # Canonical agent skill (4ge-cli.md) — ships in npm pkg
202
- ├── openapi-ts.config.ts # Configuration for the API contract sync
203
- └── package.json # Scripts and dependencies
204
- ```
205
-
206
- ## ✅ Current Implementation Status
207
-
208
- | Phase | Status | Commands Available |
209
- |-------|--------|--------------------|
210
- | Phase 1: Foundation (Auth + Config) | ✅ Complete | `auth:login | auth:status | auth:logout | auth:profile:list | auth:profile:use | auth:profile:delete`, `init`, `login`, `whoami` |
211
- | Phase 2: Read Operations | ✅ Complete | `project:list | project:info | project:pull | project:create | project:update`, `plan:pull | plan:versions`, `epic/story/feature:list | :show | :pull` |
212
- | Phase 3: Write Operations | ✅ Complete | `epic/story/feature:update`, `idea:create | idea:graduate | idea:list | idea:show | idea:update`, `template:list | template:info | template:create | template:update | template:delete`, `template:feature:create | :list | :update | :delete`, `config:set | config:get | config:show | config:manage` |
213
- | Phase 4: Enhanced UX (TUI) | ✅ Complete | Ink TUI with spinner, tables, detail views, selection prompts, action hints, `--interactive` flag, `cli.default_mode` config |
214
- | Phase 5: Advanced UX | ✅ Partial | `config:manage` ✅, `--dry-run` ✅, `--retry` ✅, hierarchy config defaults ✅, agent skill install (`skill:install`) ✅, OAuth realtime flow ✅ |
215
- | Phase 6: Flows | 🗓 Planned | `flow:list | flow:show | flow:pull | flow:update` (issue #012) |
216
-
217
-
218
- ## 🤖 AI Agent Integration
219
-
220
- This CLI is a primary tool for 4ge AI Agents. When integrating, Agents must adhere to the following rules:
221
-
222
- 1. **JSON Mode:** Always append the `--json` flag. This disables all interactive prompts and returns a deterministic, Zod-validated payload.
223
- 2. **Authentication:** Agents should bypass OAuth by providing a Personal Access Token via the `4GE_API_KEY` environment variable.
224
- 3. **Telemetry:** Agents interacting with the CLI should expect the `X-Client-Type: 4ge-agent` header to be automatically applied to upstream Core API requests.
225
- 4. **Skill install:** To teach an agent how to use the CLI, install the bundled skill into the project: `4ge skill:install` (default target `.agents/skills/4ge-cli/SKILL.md`, picked up by Cursor/Cline/Codex/Gemini CLI/GitHub Copilot/OpenCode). Use `--agent pi`/`--agent claude-code`/etc. for a specific harness, `--global` for user scope, `--force` to overwrite. `4ge init` also offers this on completion.
226
-
227
- See `skills/4ge-cli.md` for the canonical skill content (command reference, response envelope, workflow patterns).
228
120
 
121
+ `4ge init` also offers to install the skill on completion. The canonical skill
122
+ content lives at [`skills/4ge-cli.md`](./skills/4ge-cli.md) inside the package.
123
+
124
+ ## Command overview
125
+
126
+ All commands support `--json`, and mutations support `--dry-run`. Run
127
+ `<command> --help` for full flag details. The complete reference is in
128
+ [`usage.md`](./usage.md).
129
+
130
+ | Namespace | Commands |
131
+ |-----------|----------|
132
+ | `init` | Anchor the CLI to a 4ge project (offers agent skill install) |
133
+ | `whoami` · `auth:status` | Current auth status |
134
+ | `auth:login` · `auth:logout` | Authenticate / clear credentials |
135
+ | `auth:profile:list` · `:use` · `:delete` | Manage named profiles |
136
+ | `project` | `create` `info` `list` `pull` `update` |
137
+ | `epic` | `list` `show` `pull` `update` |
138
+ | `story` | `list` `show` `pull` `update` |
139
+ | `feature` | `list` `show` `pull` `update` |
140
+ | `idea` | `create` `graduate` `list` `show` `update` |
141
+ | `plan` | `pull` `versions` |
142
+ | `flow` | `list` `show` `pull` `update` |
143
+ | `template` | `create` `delete` `info` `list` `pull` `update` |
144
+ | `template:feature` | `create` `delete` `list` `update` |
145
+ | `config` | `set` `get` `show` `manage` |
146
+ | `skill` | `install` — install the agent skill for an AI harness |
147
+
148
+ ## Troubleshooting
149
+
150
+ | Symptom | Fix |
151
+ |---------|-----|
152
+ | “Not authenticated” | `4ge auth:login --token <api_key>`, or set `4GE_API_KEY`. |
153
+ | “Already initialised” | Edit `.4ge/config.yaml` directly, or delete it and re-run `4ge init`. |
154
+ | Token validation fails but credentials saved | The API was unreachable during login; credentials are saved as a fallback. Check `4GE_API_URL` and network. |
155
+ | `SINGLE_COMMAND_CLI` / loader warnings in `pnpm dev` | Harmless oclif v4 dev-mode loader warnings. |
156
+
157
+ Full troubleshooting is in [`usage.md`](./usage.md).
158
+
159
+ ## License
160
+
161
+ MIT © Conflate AI
package/dist/base.js CHANGED
@@ -413,11 +413,16 @@ export class BaseCommand extends Command {
413
413
  this.log(` Payload: ${JSON.stringify(payload, null, 2)}`);
414
414
  }
415
415
  }
416
- // Handle errors — in JSON mode output JSON error, otherwise use oclif default
416
+ // Handle errors. In JSON mode emit a structured envelope for unexpected
417
+ // errors, then re-throw so the framework sets the exit code. Intentional
418
+ // exit errors (oclif ExitError, thrown by this.exit()/outputErrorAndExit)
419
+ // are NOT re-emitted in JSON mode — the command has already produced any
420
+ // envelope it intended to, and re-emitting would double-print a trailing
421
+ // {data:null,error:{EEXIT}} envelope (#34). The framework renders
422
+ // ExitError as empty (no output) and exits non-zero, matching pretty mode.
417
423
  async catch(error) {
418
- if (this.isJsonMode) {
424
+ if (this.isJsonMode && error?.code !== 'EEXIT') {
419
425
  this.outputError({ message: error.message, code: error.code || error.constructor.name });
420
- this.exit(1);
421
426
  }
422
427
  throw error;
423
428
  }
package/dist/commands/epic/list.js CHANGED
@@ -75,7 +75,7 @@ export default class EpicList extends BaseCommand {
75
75
  const selectedId = await this.selectOption('Select an epic for details:', options, { headerVariant: 'compact' });
76
76
  if (selectedId) {
77
77
  const { default: chalk } = await import('chalk');
78
- this.log(`\n 🚀 Run: ${chalk.cyan(`4ge epic:show ${selectedId}`)}\n`);
78
+ this.log(`\n 🚀 Run: ${chalk.cyan(`4ge epic:show --id ${selectedId}`)}\n`);
79
79
  }
80
80
  }
81
81
  if (metadata?.action_hints) {
package/dist/commands/feature/list.js CHANGED
@@ -77,7 +77,7 @@ export default class FeatureList extends BaseCommand {
77
77
  const selectedId = await this.selectOption('Select a feature for details:', options, { headerVariant: 'compact' });
78
78
  if (selectedId) {
79
79
  const { default: chalk } = await import('chalk');
80
- this.log(`\n 🚀 Run: ${chalk.cyan(`4ge feature:show ${selectedId}`)}\n`);
80
+ this.log(`\n 🚀 Run: ${chalk.cyan(`4ge feature:show --id ${selectedId}`)}\n`);
81
81
  }
82
82
  }
83
83
  if (metadata?.action_hints) {
package/dist/commands/flow/list.js CHANGED
@@ -69,7 +69,7 @@ export default class FlowList extends BaseCommand {
69
69
  const selectedId = await this.selectOption('Select a flow for details:', options, { headerVariant: 'compact' });
70
70
  if (selectedId) {
71
71
  const { default: chalk } = await import('chalk');
72
- this.log(`\n 🚀 Run: ${chalk.cyan(`4ge flow:show ${selectedId}`)}\n`);
72
+ this.log(`\n 🚀 Run: ${chalk.cyan(`4ge flow:show --id ${selectedId}`)}\n`);
73
73
  }
74
74
  }
75
75
  if (metadata?.action_hints) {
package/dist/commands/idea/graduate.js CHANGED
@@ -74,8 +74,9 @@ export default class IdeaGraduate extends BaseCommand {
74
74
  if (this.isInteractiveMode) {
75
75
  const { default: chalk } = await import('chalk');
76
76
  this.log(`\n 🚀 Next steps:`);
77
- this.log(` - Project info: ${chalk.cyan(`4ge project:info --id ${result.id}`)}`);
78
- this.log(` - Pull plan: ${chalk.cyan(`4ge plan:pull --project ${result.id}`)}`);
77
+ this.log(` - Switch to it: ${chalk.cyan(`4ge init --workspace ${workspaceId} --project ${result.id}`)}`);
78
+ this.log(` - Project info: ${chalk.cyan(`4ge project:info`)}`);
79
+ this.log(` - Pull plan: ${chalk.cyan(`4ge plan:pull`)}`);
79
80
  if (metadata?.action_hints) {
80
81
  await this.handleActionHints(metadata.action_hints);
81
82
  }
package/dist/commands/project/list.js CHANGED
@@ -62,7 +62,7 @@ export default class ProjectList extends BaseCommand {
62
62
  const selectedId = await this.selectOption('Select a project for details:', options, { headerVariant: 'compact' });
63
63
  if (selectedId) {
64
64
  const { default: chalk } = await import('chalk');
65
- this.log(`\n 🚀 Run: ${chalk.cyan(`4ge project:show ${selectedId}`)}\n`);
65
+ this.log(`\n 🚀 Run: ${chalk.cyan(`4ge init --workspace ${config.workspace_id} --project ${selectedId}`)}\n`);
66
66
  }
67
67
  }
68
68
  if (metadata?.action_hints) {
package/dist/commands/story/list.js CHANGED
@@ -65,7 +65,7 @@ export default class StoryList extends BaseCommand {
65
65
  const selectedId = await this.selectOption('Select a story for details:', options, { headerVariant: 'compact' });
66
66
  if (selectedId) {
67
67
  const { default: chalk } = await import('chalk');
68
- this.log(`\n 🚀 Run: ${chalk.cyan(`4ge story:show ${selectedId}`)}\n`);
68
+ this.log(`\n 🚀 Run: ${chalk.cyan(`4ge story:show --id ${selectedId}`)}\n`);
69
69
  }
70
70
  }
71
71
  if (metadata?.action_hints) {
package/dist/commands/template/pull.js CHANGED
@@ -87,7 +87,7 @@ export default class TemplatePull extends BaseCommand {
87
87
  }
88
88
  if (this.isInteractiveMode) {
89
89
  await this.handleActionHints([
90
- { label: 'List template features', command: `4ge template:feature:list ${templateId}` },
90
+ { label: 'List template features', command: `4ge template:feature:list --id ${templateId}` },
91
91
  { label: 'Project info', command: '4ge project:info' },
92
92
  ]);
93
93
  }
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@4ge/cli",
3
- "version": "0.2.3",
4
- "description": "4ge Service Architecture Bridge & CLI",
3
+ "version": "0.2.5",
4
+ "description": "Official CLI for 4ge.",
5
5
  "main": "dist/index.js",
6
6
  "bin": {
7
7
  "4ge": "bin/run.js"
@@ -10,7 +10,7 @@
10
10
  "type": "git",
11
11
  "url": "git+https://github.com/Conflate-AI/4ge-cli.git"
12
12
  },
13
- "homepage": "https://github.com/Conflate-AI/4ge-cli#readme",
13
+ "homepage": "https://4ge.dev",
14
14
  "bugs": {
15
15
  "url": "https://github.com/Conflate-AI/4ge-cli/issues"
16
16
  },
package/skills/4ge-cli.md CHANGED
@@ -1,14 +1,14 @@
1
1
  ---
2
2
  name: 4ge-cli
3
3
  description: >
4
- Instructions for AI agents to interact with the 4ge Product Management
5
- Platform via the `4ge` CLI. Covers command syntax (namespace:command with a
6
- colon), mandatory `--json` agent mode, the response envelope, error handling,
7
- discovery, dry-run previews, retry, and the full command reference for the
8
- project / epic / story / feature / flow / idea / template / plan / auth /
9
- config / skill namespaces. Use when an agent needs to read or mutate 4ge plan
10
- assets, work with pull/list/show/update commands, or install the 4ge CLI skill
11
- for an agent harness.
4
+ Instructions for AI agents to interact with 4ge (https://4ge.dev) via the
5
+ `4ge` CLI. Covers command syntax (namespace:command with a colon), mandatory
6
+ `--json` agent mode, the response envelope, error handling, discovery,
7
+ dry-run previews, retry, and the full command reference for the project /
8
+ epic / story / feature / flow / idea / template / plan / auth / config /
9
+ skill namespaces. Use when an agent needs to read or mutate 4ge plan assets,
10
+ work with pull/list/show/update commands, or install the 4ge CLI skill for an
11
+ agent harness.
12
12
  user-invocable: true
13
13
  risk: safe
14
14
  source: https://github.com/Conflate-AI/4ge-cli/blob/main/skills/4ge-cli.md
@@ -16,8 +16,8 @@ source: https://github.com/Conflate-AI/4ge-cli/blob/main/skills/4ge-cli.md
16
16
 
17
17
  # 4ge CLI Skill
18
18
 
19
- This document provides instructions for AI agents to interact with the 4ge
20
- Product Management Platform using the `4ge` CLI.
19
+ This document provides instructions for AI agents to interact with
20
+ [4ge](https://4ge.dev) using the `4ge` CLI.
21
21
 
22
22
  ## 🚨 Preconditions (User Action Required)
23
23
  Before using this CLI, the user **MUST** have completed:
@@ -107,20 +107,20 @@ Use it for network-flaky operations.
107
107
 
108
108
  ## 📋 Command Reference
109
109
 
110
- | Namespace | Commands | Key Flags |
110
+ | Namespace | Commands | Key Flags (bold = required) |
111
111
  |-----------|----------|-----------|
112
- | **project** | `create`, `info`, `list`, `pull`, `update` | `--workspace` (create), `--name`, `--description`, `--template`, `--force`, `--save`/`--stdout` (pull), `--dry-run`, `--retry` |
113
- | **epic** | `list`, `show`, `pull`, `update` | `--epic-id` / `--id` (pull), `--status`, `--title`, `--recursive` (pull), `--roadmap` (pull, with `--recursive`), `--save`/`--stdout` (pull), `--dry-run`, `--retry` |
114
- | **flow** | `list`, `show`, `pull`, `update` | `--id`, `--feature-id` (list), `--recursive` (pull — full flow step tree), `--status`, `--title` (update), `--description` (update), `--priority` (update), `--roadmap-status` (update), `--save`/`--stdout` (pull), `--dry-run`, `--retry` |
115
- | **story** | `list`, `show`, `pull`, `update` | `--story-id` / `--id` (pull), `--status`, `--title`, `--recursive` (pull), `--roadmap` (pull, with `--recursive`), `--save`/`--stdout` (pull), `--dry-run`, `--retry` |
116
- | **feature** | `list`, `show`, `pull`, `update` | `--feature-id` / `--id` (pull), `--status`, `--roadmap`, `--recursive` (pull), `--roadmap` (pull, with `--recursive`), `--save`/`--stdout` (pull), `--dry-run`, `--retry` |
117
- | **idea** | `create`, `graduate`, `list`, `show`, `update` | `<ID>` (positional for show), `--title`, `--workspace`, `--dry-run`, `--retry` |
118
- | **template** | `create`, `delete`, `info`, `list`, `pull`, `update` | `--id`, `--name`, `--workspace`, `--description`, `--force`, `--save`/`--stdout` (pull), `--dry-run`, `--retry` |
119
- | **template:feature** | `create`, `delete`, `list`, `update` | `--id`, `--template-id`, `--name`, `--description`, `--status`, `--dry-run`, `--retry` |
120
- | **plan** | `pull`, `versions` | `--roadmap` (now\|next\|later), `--status`, `--save`, `--stdout`, `--retry` |
121
- | **auth** | `status`, `logout`, `profile:list`, `profile:use`, `profile:delete` | *(login/logout are user-only)* |
122
- | **config** | `set`, `get`, `show`, `manage` | `manage` opens interactive config editor; `set`/`get` take `key` / `key=value` |
123
- | **skill** | `install` | `--agent`, `--global`, `--force` (installs this skill file for an agent harness) |
112
+ | **project** | `create`, `info`, `list`, `pull`, `update` | **`--workspace`** (create), **`--name`** (create), `--description`, `--template`, `--force`, `--save`/`--stdout` (pull), `--dry-run`, `--retry` |
113
+ | **epic** | `list`, `show`, `pull`, `update` | **`--id`** (show/pull/update), `--status`, `--title`, `--recursive` (pull), `--roadmap` (pull, with `--recursive`), `--save`/`--stdout` (pull), `--dry-run`, `--retry` |
114
+ | **flow** | `list`, `show`, `pull`, `update` | **`--feature-id`** (list), **`--id`** (show/pull/update), `--recursive` (pull — full flow step tree), `--status`, `--title` (update), `--description` (update), `--priority` (update), `--roadmap-status` (update), `--save`/`--stdout` (pull), `--dry-run`, `--retry` |
115
+ | **story** | `list`, `show`, `pull`, `update` | **`--id`** (show/pull/update), `--status`, `--title`, `--recursive` (pull), `--roadmap` (pull, with `--recursive`), `--save`/`--stdout` (pull), `--dry-run`, `--retry` |
116
+ | **feature** | `list`, `show`, `pull`, `update` | **`--id`** (show/pull/update), `--status`, `--roadmap`, `--recursive` (pull), `--roadmap` (pull, with `--recursive`), `--save`/`--stdout` (pull), `--dry-run`, `--retry` |
117
+ | **idea** | `create`, `graduate`, `list`, `show`, `update` | **`<ID>`** (positional: show/update/graduate), **`--title`** (create), **`--workspace`** (list/create — unless `.4ge/config.yaml` has `workspace_id`), `--dry-run`, `--retry` |
118
+ | **template** | `create`, `delete`, `info`, `list`, `pull`, `update` | **`--id`** (info/update/delete), **`--name`** (create), **`--workspace-id`** (create), `--description`, `--force`, `--save`/`--stdout` (pull), `--dry-run`, `--retry` |
119
+ | **template:feature** | `create`, `delete`, `list`, `update` | **`--id`** (all — the template id), **`--feature-id`** (update/delete), **`--name`** (create), `--description`, `--status`, `--public` (create), `--dry-run`, `--retry` | **note:** `--id` is `required: true` on every `template:feature` subcommand |
120
+ | **plan** | `pull`, `versions` | `--roadmap` (now\|next\|later), `--status`, `--save`, `--stdout`, `--retry` (no required flags — reads `.4ge/config.yaml` project) |
121
+ | **auth** | `status`, `logout`, `profile:list`, `profile:use`, `profile:delete` | `profile:use`/`profile:delete` take a **`<name>` positional arg**; *(login/logout are user-only)* |
122
+ | **config** | `set`, `get`, `show`, `manage` | `manage` opens interactive config editor; `set` takes **`key value`** and `get` takes **`key`** (both positional, required) |
123
+ | **skill** | `install` | `--agent`, `--global`, `--force` (none required) — installs this skill file for an agent harness |
124
124
  | *(root)* | `init`, `whoami` | `init` sets up `.4ge/config.yaml`; `whoami` aliases `auth:status` |
125
125
 
126
126
  ### Project context
package/usage.md CHANGED
@@ -1,6 +1,8 @@
1
1
  # 4ge CLI Usage Guide
2
2
 
3
- > A Universal Interface for 4ge Resources
3
+ > The official command-line interface for [4ge](https://4ge.dev).
4
+ >
5
+ > See the [README](./README.md) for an overview, and <https://4ge.dev> for the product.
4
6
 
5
7
  ## Installation & Setup
6
8
 
@@ -302,7 +304,7 @@ full flag details.
302
304
  | `config` | `set` `get` `show` `manage` |
303
305
  | `skill` | `install` — install the agent skill for an AI harness |
304
306
 
305
- > `flow:*` commands are planned (not yet shipped).
307
+ > `flow:*` commands are shipped (`list | show | pull | update`).
306
308
 
307
309
 
308
310
  ## Troubleshooting