atk-cli 0.1.2__tar.gz → 0.2.1__tar.gz

atk_cli-0.2.1/.github/ISSUE_TEMPLATE/bug_report.md

@@ -0,0 +1,20 @@
+---
+name: Bug report
+about: Something isn't working
+labels: bug
+---
+
+**ATK version** (`atk --version`):
+
+**What happened:**
+
+**What you expected:**
+
+**Steps to reproduce:**
+
+```bash
+# minimal reproduction
+```
+
+**OS:**
+

atk_cli-0.2.1/.github/ISSUE_TEMPLATE/feature_request.md

@@ -0,0 +1,12 @@
+---
+name: Feature request
+about: Suggest an improvement or new capability
+labels: enhancement
+---
+
+**What problem does this solve?**
+
+**Proposed solution:**
+
+**Alternatives considered:**
+

atk_cli-0.2.1/.github/pull_request_template.md

@@ -0,0 +1,14 @@
+## What
+
+<!-- What does this PR change? -->
+
+## Why
+
+<!-- Why is this change needed? -->
+
+## Tests
+
+- [ ] Automated tests added or updated
+- [ ] `make check` passes
+- [ ] Manually tested (describe what you ran)
+

atk_cli-0.2.1/.github/workflows/ci.yml

@@ -0,0 +1,47 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  check:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: uv sync
+
+      - name: Run checks
+        run: make check
+
+      - name: Run tests with coverage (3.11 only)
+        if: matrix.python-version == '3.11'
+        run: uv run coverage run -m pytest
+
+      - name: Generate XML coverage report (3.11 only)
+        if: matrix.python-version == '3.11'
+        run: uv run coverage xml
+
+      - name: Upload coverage to Codecov (3.11 only)
+        if: matrix.python-version == '3.11'
+        uses: codecov/codecov-action@v5
+        with:
+          files: ./coverage.xml
+          use_oidc: true
+          fail_ci_if_error: false

atk_cli-0.2.1/CODE_OF_CONDUCT.md

@@ -0,0 +1,36 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our community
+a harassment-free experience for everyone, regardless of age, body size, visible or invisible
+disability, ethnicity, sex characteristics, gender identity and expression, level of experience,
+education, socio-economic status, nationality, personal appearance, race, caste, color,
+religion, or sexual identity and orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+- Demonstrating empathy and kindness toward other people
+- Being respectful of differing opinions, viewpoints, and experiences
+- Giving and gracefully accepting constructive feedback
+- Accepting responsibility and apologizing to those affected by our mistakes
+
+Examples of unacceptable behavior:
+
+- Sexualized language or imagery, and unwelcome sexual attention or advances
+- Trolling, insulting or derogatory comments, and personal or political attacks
+- Public or private harassment
+- Publishing others' private information without explicit permission
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be reported
+to the project maintainer at **sasha@svtoo.com**. All complaints will be reviewed
+and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org), version 2.1.
+

atk_cli-0.2.1/CONTRIBUTING.md

@@ -0,0 +1,51 @@
+# Contributing to ATK
+
+Thanks for your interest. ATK is an early-stage tool — contributions are welcome.
+
+## Getting started
+
+```bash
+git clone https://github.com/Svtoo/atk
+cd atk
+uv sync --dev
+```
+
+## Making changes
+
+- Open an issue first for non-trivial changes.
+- Keep PRs focused — one concern per PR.
+- Match existing code style (ruff + mypy strict).
+
+## Tests
+
+All code changes must include automated tests.
+
+```bash
+# Run the full test suite
+uv run pytest
+
+# Lint and type-check
+uv run ruff check src tests
+uv run mypy src
+```
+
+If you're adding a command or changing CLI behaviour, also test it manually:
+
+```bash
+uv run atk <your command>
+```
+
+The CI must pass before a PR is merged.
+
+## Submitting a PR
+
+1. Fork and create a branch from `main`.
+2. Write or update tests for your change.
+3. Run `make check` — all must pass.
+4. Open a PR with a clear description of what changed and why.
+
+## Adding a registry plugin
+
+Submit a PR to [atk-registry](https://github.com/Svtoo/atk-registry), not this repo.
+See the registry README for schema requirements.
+

atk_cli-0.2.1/PKG-INFO

@@ -0,0 +1,416 @@
+Metadata-Version: 2.4
+Name: atk-cli
+Version: 0.2.1
+Summary: AI Toolkit - Manage AI development tools through a git-backed, declarative manifest
+Project-URL: Homepage, https://github.com/Svtoo/atk
+Project-URL: Repository, https://github.com/Svtoo/atk
+Project-URL: Issues, https://github.com/Svtoo/atk/issues
+Author-email: "Oleksandr (Sasha) Antoshchenko" <sasha@svtoo.com>
+License: Apache-2.0
+License-File: LICENSE
+Keywords: agent,ai,cli,devtools,mcp,tools
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Operating System :: MacOS
+Classifier: Operating System :: POSIX :: Linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Software Development :: Build Tools
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.0
+Requires-Dist: python-dotenv>=1.2.1
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.12
+Description-Content-Type: text/markdown
+
+<p align="center">
+  <img src="assets/logo.png" alt="ATK Logo" width="280px">
+</p>
+
+<p align="center">
+  <a href="https://github.com/Svtoo/atk/actions/workflows/ci.yml"><img src="https://github.com/Svtoo/atk/actions/workflows/ci.yml/badge.svg" alt="CI"></a>
+  <a href="https://codecov.io/gh/Svtoo/atk"><img src="https://codecov.io/gh/Svtoo/atk/branch/main/graph/badge.svg" alt="Coverage"></a>
+  <a href="https://pypi.org/project/atk-cli/"><img src="https://img.shields.io/pypi/v/atk-cli" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/atk-cli/"><img src="https://img.shields.io/pypi/dm/atk-cli" alt="PyPI downloads"></a>
+  <a href="https://pypi.org/project/atk-cli/"><img src="https://img.shields.io/pypi/pyversions/atk-cli" alt="Python versions"></a>
+  <a href="LICENSE"><img src="https://img.shields.io/github/license/Svtoo/atk" alt="License"></a>
+</p>
+
+# ATK — AI Tool Kit for Developers
+
+ATK is a **CLI plugin manager for AI-assisted development**.
+
+Install MCP servers and local AI services with one command. Wire them into every coding agent you use — Claude Code, Codex, Gemini CLI, Augment Code, OpenCode — simultaneously. Keep your entire setup git-backed, reproducible, and upgradeable.
+
+> **Install. Wire. Done.**
+> `atk add github` → `atk mcp add github --claude --codex --auggie`
+
+<p align="center">
+  <img src="assets/demo-hero.gif" alt="ATK: wire one MCP into multiple agents" width="700px">
+</p>
+
+---
+
+## The problem
+
+If you use coding agents seriously, your setup probably looks like this:
+
+- MCP servers installed from random Git repos, each with its own README to follow
+- Local services started with long-forgotten `docker run` commands
+- Agent configs hand-edited in JSON files scattered across your machine
+- The same MCP configured differently in Claude, Codex, and Augment because you did it three times manually
+- Secrets in `.env` files with no connection to anything
+
+It works. Until you switch machines, break something, want to roll back, or come back after two months and have no idea what’s running or how it got there.
+
+ATK exists because this setup is **real, fragile, and universal**.
+
+---
+
+## What ATK does
+
+**Discover and install AI tools from a curated registry**
+
+```bash
+atk search                  # browse vetted plugins
+atk add github              # install in one command, prompts for config
+atk status                  # see what's running, ports, env status
+```
+
+**Wire MCPs into all your coding agents at once**
+
+```bash
+atk mcp add github --claude --codex --gemini --auggie --opencode
+```
+
+One command. ATK calls each agent’s native MCP registration command, or writes the config file directly. No manual JSON editing across multiple apps.
+
+**Teach your agents how to use the tools**
+
+When a plugin ships a `SKILL.md` — usage instructions for AI agents — ATK injects it into each agent’s context automatically. Claude gets `@`-references in `CLAUDE.md`. Codex gets read-directives in `AGENTS.md`. Gemini and Augment Code gets a symlink in `~/.gemini/skills/`, `~/.augment/rules/` respectively. OpenCode gets an entry in its `instructions` array.
+
+Your agent doesn’t just have access to the tool — it knows **how** and **when** to use it.
+
+**Manage the full lifecycle of everything**
+
+```bash
+atk start openmemory        # start a service
+atk stop langfuse           # stop it
+atk logs openmemory         # tail logs
+atk upgrade --all           # pull latest for all plugins
+atk remove github           # stop + uninstall + delete
+```
+
+Every tool — Docker service, MCP server, CLI binary — gets the same uniform interface.
+
+---
+
+## Supported agents
+
+| Agent | MCP registration | Skill injection |
+|-------|-----------------|-----------------|
+| [Claude Code](https://claude.ai/code) | `claude mcp add` | `~/.claude/CLAUDE.md` |
+| [Codex](https://github.com/openai/codex) | `codex mcp add` | `~/.codex/AGENTS.md` |
+| [Gemini CLI](https://github.com/google-gemini/gemini-cli) | `gemini mcp add` | `~/.gemini/skills/` (dir symlink) |
+| [Augment Code](https://augmentcode.com) | `auggie mcp add-json` | `~/.augment/rules/` |
+| [OpenCode](https://opencode.ai) | writes `opencode.jsonc` | `opencode.jsonc` instructions |
+
+You can target one, several, or all at once with agent flags.
+
+---
+
+## Registry
+
+```
+$ atk search
+11 plugins
+
+  NAME                  DESCRIPTION
+    fetch               Web content fetching via MCP
+    git-local           Safe Git operations on local repos via MCP
+    github              GitHub: search repos, file issues, open PRs from chat
+    gitlab              GitLab issues, MRs, file reading via Duo MCP
+    google-workspace    Gmail, Drive, Calendar, Docs, Sheets from any AI assistant
+    langfuse            Open-source LLM observability and tracing
+    notion              Search pages, read/write content, manage databases
+    openmemory          Persistent memory layer for AI agents with semantic search
+    piper               Local text-to-speech with neural voices
+    playwright          Browser automation: screenshots, web interaction, JS execution
+    slack               List channels, read history, post messages, look up users
+```
+
+All registry plugins are reviewed, schema-validated, and versioned. Installed plugins are marked with `✓`. Search by keyword: `atk search memory`, `atk search git`.
+
+<p align="center">
+  <img src="assets/demo-search.gif" alt="atk search — live registry" width="700px">
+</p>
+
+---
+
+## Getting started
+
+<details>
+<summary><strong>Prerequisite: install uv (recommended Python tool runner)</strong></summary>
+
+- **macOS:** `brew install uv`
+- **Other:** [Official Install Guide](https://docs.astral.sh/uv/getting-started/installation/)
+
+</details>
+
+```bash
+# Install ATK
+uv tool install atk-cli      # recommended
+# or: pip install atk-cli
+
+# Initialize ATK Home (defaults to ~/.atk — a git repo)
+atk init
+
+# Browse available plugins
+atk search
+
+# Add a plugin — installs it and prompts for any config it needs
+atk add openmemory
+
+# Check what's running
+atk status
+
+# Wire the MCP into your coding agents (with skill instructions)
+atk mcp add openmemory --claude --auggie
+
+# See the raw MCP config (copy-paste into any tool that reads JSON)
+atk mcp show openmemory
+```
+
+Your entire setup lives in `~/.atk/` — a git repository. Push it. Clone it on another machine. Run `atk install --all`. Everything comes back exactly as you left it.
+
+<p align="center">
+  <img src="assets/demo-status.gif" alt="atk status — live service dashboard" width="700px">
+</p>
+
+---
+
+## Command reference
+
+| Command | What it does |
+|---------|--------------|
+| `atk search [query]` | Browse or filter registry plugins |
+| `atk add <name\|url\|path>` | Install a plugin, prompts for config |
+| `atk setup <plugin>` | Re-configure environment variables |
+| `atk status` | Show all plugins: running state, ports, env |
+| `atk start / stop / restart` | Lifecycle control |
+| `atk logs <plugin>` | Tail service logs |
+| `atk upgrade [--all]` | Pull latest plugin version |
+| `atk remove <plugin>` | Stop + uninstall + delete |
+| `atk mcp show <plugin>` | Print MCP config (plaintext or `--json`) |
+| `atk mcp add <plugin> [--claude] [--codex] [--gemini] [--auggie] [--opencode]` | Register with agents + inject skill |
+| `atk mcp remove <plugin> [agents...]` | Unregister from agents |
+| `atk help <plugin>` | Render plugin README in terminal |
+| `atk run <plugin> <script>` | Run a plugin's custom script |
+
+---
+
+## ATK plugins and registry
+
+ATK is built around **plugins**.
+
+A plugin describes how to install, configure, run, update, and integrate a tool or service — including MCPs, local services, CLIs, or agent-facing components.
+
+ATK supports **three ways** to work with plugins:
+
+### 1. Official ATK Registry (vetted plugins)
+
+ATK maintains a growing **registry of vetted plugins** for common tools in AI-assisted development.
+
+Install by name:
+
+```bash
+atk add openmemory
+atk add langfuse
+```
+
+Registry plugins are reviewed, schema-validated, versioned, and pinned. Think of this as the "known good" layer.
+
+### 2. Git repository plugins (distribution channel)
+
+Any Git repository can become an ATK plugin. Add a `.atk/plugin.yaml` to your repo and users can install it with one line:
+
+```bash
+atk add github.com/your-org/your-tool
+```
+
+ATK sparse-clones only the `.atk/` directory, validates the plugin, pins it to a commit hash, and manages its lifecycle like any other plugin. This turns ATK into a **distribution channel for AI tooling** — without a centralized gatekeeper.
+
+### 3. Local plugins (personal or internal tooling)
+
+```bash
+atk add ./my-plugin
+```
+
+Lives in `~/.atk`, fully versioned, uses the same schema. Ideal for personal scripts, internal tools, or plugins in development.
+
+---
+
+## Reproducibility
+
+ATK environments are fully reproducible:
+
+- Plugins are validated against a **versioned schema**
+- Plugin versions are **pinned** to exact commit hashes in the manifest
+- Secrets live in isolated, gitignored `.env` files
+- Every mutation is a **git commit** — rollback is `git revert`
+- Additive schema changes are backward-compatible
+
+Clone the repo on a new machine. Run `atk install --all`. You get the same toolchain.
+
+---
+
+## Unified lifecycle
+
+ATK gives every tool the same lifecycle, regardless of how it is installed.
+
+```bash
+atk start openmemory
+atk stop openmemory
+atk restart openmemory
+atk status
+atk logs openmemory
+```
+
+This works whether the tool is a Docker service, a Python CLI, a Node binary, or a custom shell-based MCP server.
+
+---
+
+## Design principles
+
+| Principle   | Meaning                                               |
+| ----------- | ----------------------------------------------------- |
+| Declarative | The manifest describes desired state; ATK enforces it |
+| Idempotent  | Running the same command twice yields the same result |
+| Git-native  | Every mutation is a commit; rollback = `git revert`   |
+| Transparent | Human-readable YAML; no hidden state                  |
+| AI-first    | CLI-driven, scriptable, agent-friendly                |
+| Focused     | Manages tools, doesn't build them                     |
+
+---
+
+## Who ATK is for
+
+ATK is for developers who:
+
+- rely on coding agents (Claude Code, Codex, Augment Code, etc.)
+- don't want to be vendor-locked, or work with multiple tools
+- use MCP servers (local and remote)
+- run local services like memory, observability, or vector stores
+- care about owning their data and controlling their setup
+
+ATK is not limited to people building AI models. It is for people **building software with AI systems in the loop**.
+
+---
+
+## What ATK is (and is not)
+
+**ATK is:**
+- a toolchain and plugin manager for developers
+- focused on local, long-lived AI tooling
+- git-backed and reproducible
+- CLI-first and automation-friendly
+- designed to be driven by humans *and* coding agents
+
+**ATK is not:**
+- an environment manager (Nix, Conda, Devbox)
+- infrastructure-as-code (Terraform, Ansible)
+- a production deployment system
+- project-scoped
+
+If you're configuring servers, ATK is the wrong tool.
+If you're keeping your **AI dev setup sane**, it's the right one.
+
+---
+
+## Installation
+
+```bash
+# Recommended
+uv tool install atk-cli
+
+# Alternative
+pip install atk-cli
+```
+
+ATK is distributed via **PyPI** and installs as a single self-contained CLI. Requires Python 3.11+.
+
+---
+
+## For MCP authors: ATK as your distribution layer
+
+If you’re building an MCP server, ATK is the easiest way to get it into your users’ agents.
+
+### What you get
+
+**One-command install from your repo**
+
+```bash
+atk add github.com/you/your-mcp-server
+```
+
+ATK sparse-clones only the `.atk/` directory from your repo, validates it, and pins it to a commit hash. Your users run one command and have a working, managed, upgradeable installation.
+
+**Automatic agent wiring — all agents at once**
+
+```bash
+atk mcp add your-mcp-server --claude --codex --gemini --auggie --opencode
+```
+
+ATK handles the agent-specific plumbing: native CLI commands for Claude and Codex, JSON config writing for OpenCode, everything. Your users don’t need to know which config file to edit or which flags to pass.
+
+**You control how agents use your tool**
+
+Ship a `SKILL.md` alongside your plugin. When users run `atk mcp add`, ATK injects it into each agent’s context automatically:
+
+- **Claude Code**: added to `~/.claude/CLAUDE.md` as an `@`-reference
+- **Codex**: added to `~/.codex/AGENTS.md` as a read-directive
+- **Augment Code**: symlinked into `~/.augment/rules/` (auto-loaded every session)
+- **OpenCode**: added to the `instructions` array in `opencode.jsonc`
+- **Gemini CLI**: symlinked into `~/.gemini/skills/`
+
+The agent doesn’t just have access — it has instructions. You decide what the agent knows about your tool, how it should use it, and what it should avoid.
+
+### How to add ATK support to your repo
+
+You don’t need to write the plugin files by hand. ATK ships a dedicated skill file that tells your coding agent exactly what to build: the schema, lifecycle scripts, `SKILL.md` conventions, testing protocol, and all three distribution patterns.
+
+**[ATK Plugin Creation Skill →](skills/create-atk-plugin/SKILL.md)**
+
+Feed it to your agent and ask:
+
+> *"Create an ATK plugin for [your tool name]. Follow the skill file."*
+
+The agent will produce a complete `plugin.yaml`, install and lifecycle scripts, `SKILL.md`, and `README.md` — ready to ship.
+
+Once the files are ready, test locally then share via your existing repo:
+
+```bash
+atk add ./.atk                       # install locally to test
+atk add github.com/you/your-repo     # users install from your git URL
+```
+
+### Getting listed in the registry
+
+The [ATK registry](https://github.com/Svtoo/atk-registry) is the curated list of plugins available via `atk search`. Submit a PR to add your plugin. Registry plugins are reviewed and must meet the schema requirements — verified plugins get a `verified` badge in `atk status`.
+
+---
+
+## Status
+
+ATK is under active development.
+Expect fast iteration and opinionated choices.
+
+If this problem resonates with you, try it — and break it.
+
+If ATK saves you time, a ⭐ on [GitHub](https://github.com/Svtoo/atk) goes a long way.