ion-cli

Category: Tools & Productivity | Uploader: Roger-luo | Downloads: 0 | Version: v1.0（Latest）

Operate the Ion skill manager from CLI using --json flag for structured, non-interactive control of skill installation, search, and project management.

Changelog: Source: GitHub https://github.com/Roger-luo/Ion

Directory Structure

Current level: Root

📁 .github/
- 📁 workflows/
  - 📄 release-plz.yml 3.2 KB
  - 📄 release.yml 2.0 KB
📁 crates/
- 📁 ion-skill/
  - 📁 src/
    
    📁 search/
    
    📄 agent.rs 3.6 KB
    
    📄 cache.rs 4.5 KB
    
    📄 github.rs 20.4 KB
    
    📄 mod.rs 15.6 KB
    
    📄 registry.rs 3.2 KB
    
    📄 skills_sh.rs 6.1 KB
    
    📁 update/
    
    📄 binary.rs 2.6 KB
    
    📄 git.rs 8.7 KB
    
    📄 mod.rs 1.1 KB
    
    📁 validate/
    
    📄 codeblock.rs 4.0 KB
    
    📄 discovery.rs 2.8 KB
    
    📄 markdown.rs 4.1 KB
    
    📄 mod.rs 6.9 KB
    
    📄 security.rs 9.5 KB
    
    📄 structure.rs 5.7 KB
    
    📄 binary.rs 35.8 KB
    
    📄 config.rs 17.7 KB
    
    📄 error.rs 1.3 KB
    
    📄 git.rs 7.4 KB
    
    📄 gitignore.rs 9.0 KB
    
    📄 installer.rs 21.1 KB
    
    📄 lib.rs 801 B
    
    📄 lockfile.rs 5.6 KB
    
    📄 manifest.rs 12.2 KB
    
    📄 manifest_writer.rs 11.4 KB
    
    📄 migrate.rs 10.8 KB
    
    📄 registry.rs 6.0 KB
    
    📄 skill.rs 4.8 KB
    
    📄 source.rs 6.9 KB
  - 📄 Cargo.toml 582 B
  - 📄 CHANGELOG.md 32.0 KB
📁 docs/
- 📁 plans/
  - 📄 2026-03-01-codebase-simplification-design.md 5.2 KB
  - 📄 2026-03-01-codebase-simplification-plan.md 42.4 KB
  - 📄 2026-03-01-config-command-design.md 5.3 KB
  - 📄 2026-03-01-config-command-plan.md 50.4 KB
  - 📄 2026-03-01-global-config-design.md 3.3 KB
  - 📄 2026-03-01-global-config-plan.md 19.4 KB
  - 📄 2026-03-01-ion-implementation-plan.md 66.8 KB
  - 📄 2026-03-01-ion-skill-manager-design.md 6.3 KB
  - 📄 2026-03-01-search-command-design.md 3.4 KB
  - 📄 2026-03-01-search-command-plan.md 33.8 KB
  - 📄 2026-03-01-search-tui-design.md 4.1 KB
  - 📄 2026-03-01-search-tui-plan.md 17.3 KB
  - 📄 2026-03-01-symlink-installation-design.md 2.8 KB
  - 📄 2026-03-01-symlink-installation-plan.md 20.3 KB
  - 📄 2026-03-02-init-command-design.md 3.1 KB
  - 📄 2026-03-02-init-command-plan.md 12.7 KB
  - 📄 2026-03-02-ion-init-target-discoverability-design.md 3.9 KB
  - 📄 2026-03-02-ion-init-target-discoverability-plan.md 24.8 KB
  - 📄 2026-03-02-new-command-design.md 3.6 KB
  - 📄 2026-03-02-new-command-plan.md 12.3 KB
  - 📄 2026-03-02-skill-validation-design.md 4.8 KB
  - 📄 2026-03-02-skill-validation-expansion-design.md 4.9 KB
  - 📄 2026-03-02-skill-validation-expansion-plan.md 14.5 KB
  - 📄 2026-03-02-skill-validation-plan.md 45.7 KB
  - 📄 2026-03-02-symlink-gitignore-design.md 5.6 KB
  - 📄 2026-03-02-symlink-gitignore-plan.md 36.8 KB
  - 📄 2026-03-04-binary-cli-skills-design.md 6.5 KB
  - 📄 2026-03-04-binary-cli-skills-phase2-plan.md 3.2 KB
  - 📄 2026-03-04-binary-cli-skills-plan.md 43.5 KB
  - 📄 2026-03-04-update-non-binary-skills-design.md 2.6 KB
  - 📄 2026-03-04-update-non-binary-skills-plan.md 35.6 KB
  - 📄 2026-03-05-binary-cli-skills-phase3-plan.md 6.5 KB
  - 📄 2026-03-05-binary-cli-skills-phase4-plan.md 3.6 KB
  - 📄 2026-03-05-command-reorganization-design.md 2.4 KB
  - 📄 2026-03-05-command-reorganization-plan.md 11.0 KB
  - 📄 2026-03-06-ion-self-design.md 4.0 KB
  - 📄 2026-03-06-ion-self-plan.md 12.5 KB
  - 📄 2026-03-06-local-skills-design.md 3.6 KB
  - 📄 2026-03-06-local-skills-plan.md 33.6 KB
  - 📄 2026-03-07-completion-design.md 1.1 KB
  - 📄 2026-03-07-completion-implementation.md 5.3 KB
  - 📄 2026-03-09-json-agent-interface-design.md 3.9 KB
  - 📄 2026-03-09-json-agent-interface-plan.md 27.2 KB
- 📄 binary-skills-guide.md 3.7 KB
📁 src/
- 📁 commands/
  - 📄 add.rs 21.0 KB
  - 📄 completion.rs 154 B
  - 📄 config.rs 6.1 KB
  - 📄 eject.rs 5.8 KB
  - 📄 gc.rs 2.1 KB
  - 📄 info.rs 4.8 KB
  - 📄 init.rs 6.6 KB
  - 📄 install.rs 10.2 KB
  - 📄 link.rs 2.7 KB
  - 📄 list.rs 3.6 KB
  - 📄 migrate.rs 5.5 KB
  - 📄 mod.rs 296 B
  - 📄 new.rs 12.3 KB
  - 📄 remove.rs 5.8 KB
  - 📄 run.rs 1.3 KB
  - 📄 search.rs 12.2 KB
  - 📄 self_cmd.rs 7.2 KB
  - 📄 update.rs 7.0 KB
  - 📄 validate.rs 5.1 KB
  - 📄 validation.rs 6.1 KB
- 📁 tui/
  - 📄 app.rs 7.5 KB
  - 📄 event.rs 7.6 KB
  - 📄 init_select.rs 27.6 KB
  - 📄 mod.rs 154 B
  - 📄 search_app.rs 3.0 KB
  - 📄 search_event.rs 734 B
  - 📄 search_ui.rs 9.2 KB
  - 📄 terminal.rs 960 B
  - 📄 ui.rs 6.5 KB
  - 📄 util.rs 1.5 KB
- 📄 builtin_skill.rs 2.2 KB
- 📄 context.rs 1.8 KB
- 📄 json.rs 1.2 KB
- 📄 main.rs 9.2 KB
- 📄 style.rs 1.7 KB
📁 tests/
- 📄 binary_integration.rs 10.4 KB
- 📄 completion_integration.rs 2.1 KB
- 📄 config_integration.rs 1.7 KB
- 📄 integration.rs 20.8 KB
- 📄 json_integration.rs 4.9 KB
- 📄 migrate_integration.rs 6.1 KB
- 📄 new_integration.rs 7.9 KB
- 📄 search_integration.rs 1.2 KB
- 📄 update_integration.rs 9.9 KB
- 📄 validate_integration.rs 2.7 KB
📄 .gitignore 55 B
📄 AGENTS.md 5.0 KB
📄 build.rs 113 B
📄 Cargo.lock 66.5 KB
📄 Cargo.toml 477 B
📄 CHANGELOG.md 7.5 KB
📄 CLAUDE.md 39 B
📄 install.sh 5.4 KB
📄 README.md 2.2 KB
📄 release-plz.toml 894 B
📄 SKILL.md 4.2 KB
📄 skills-lock.json 2.9 KB

SKILL.md

---
name: ion-cli
description: "Operate the Ion skill manager from CLI using --json flag for structured, non-interactive control of skill installation, search, and project management."
compatibility:
  - claude
  - cursor
  - windsurf
---

# Ion CLI for Agents

Operate the Ion skill manager programmatically using the `--json` flag.

## JSON Interface

All commands support `ion --json <command>`. The `--json` flag:

- Outputs structured JSON to stdout
- Disables all interactive prompts (TUI, confirmations)
- Uses a two-stage pattern: commands that need decisions return options (exit 2), you re-run with explicit flags

### Response Envelope

```json
{"success": true, "data": { ... }}
{"success": false, "action_required": "<type>", "data": { ... }}
{"success": false, "error": "message"}
```

### Exit Codes

- `0` — success
- `1` — error
- `2` — action required (re-run with explicit flags)

## Commands

### Initialize a project

```bash
# Discover available targets
ion --json project init
# Exit 2, returns: {"action_required": "target_selection", "data": {"available_targets": [...]}}

# Initialize with specific targets
ion --json project init --target claude
ion --json project init --target claude --target cursor
```

### Search for skills

```bash
ion --json search "code review"
# Returns: {"success": true, "data": [{"name": "...", "source": "...", "description": "...", "stars": N}, ...]}
```

Use the `source` field from results to install a skill.

### Add a skill

```bash
# Single skill — succeeds directly
ion --json add owner/repo/skill-name

# Single skill with validation warnings
ion --json add owner/repo/skill-name
# Exit 2 if warnings: {"action_required": "validation_warnings", "data": {"skill": "...", "warnings": [...]}}
# Re-run to accept:
ion --json add owner/repo/skill-name --allow-warnings

# Skill collection — returns discovered skills
ion --json add owner/repo
# Exit 2: {"action_required": "skill_selection", "data": {"skills": [{"name": "...", "status": "clean|warnings|error"}, ...]}}
# Install specific skills:
ion --json add owner/repo --skills skill-a,skill-b
ion --json add owner/repo --skills skill-a,skill-b --allow-warnings
```

### Install all from Ion.toml

```bash
ion --json add
# If warnings exist and --allow-warnings not set: exit 2
ion --json add --allow-warnings
```

### Remove a skill

```bash
# Preview what will be removed
ion --json remove skill-name
# Exit 2: {"action_required": "confirm_removal", "data": {"skills": ["skill-name"]}}

# Confirm removal
ion --json remove skill-name --yes
```

### List installed skills

```bash
ion --json skill list
```

### Show skill info

```bash
ion --json skill info skill-name
```

### Update skills

```bash
ion --json update          # update all
ion --json update skill-name  # update one
```

### Validate skills

```bash
ion --json skill validate
ion --json skill validate path/to/SKILL.md
```

### Configuration

```bash
ion --json config list
ion --json config get targets.claude
ion --json config set targets.claude .claude/skills
ion --json config list --project
```

### Cache management

```bash
ion --json cache gc
ion --json cache gc --dry-run
```

### Self management

```bash
ion --json self info      # version, target, exe path
ion --json self check     # check for updates
ion --json self update    # update ion itself
```

## Typical Agent Workflow

```bash
# 1. Initialize project if needed
ion --json project init --target claude

# 2. Search for relevant skills
ion --json search "testing"

# 3. Install skills from search results (use the "source" field)
ion --json add obra/skills/test-driven-development

# 4. Handle warnings if they come back (exit code 2)
ion --json add some/skill --allow-warnings

# 5. List what's installed
ion --json skill list

# 6. Remove a skill
ion --json remove old-skill --yes
```

## Key Flags

| Flag | Scope | Purpose |
|------|-------|---------|
| `--json` | Global | Structured JSON output, no prompts |
| `--allow-warnings` | `add` | Proceed despite validation warnings |
| `--skills a,b,c` | `add` | Select specific skills from a collection |
| `--yes` / `-y` | `remove` | Skip removal confirmation |
| `--target name` | `project init` | Specify targets non-interactively |
| `--force` | `project init`, `skill new` | Overwrite existing files |

Comments 0

Latest | Hot

Please login before commenting.

No comments yet. Be the first one!

ion-cli

Directory Structure

SKILL.md

Report

Notice