Metadata-Version: 2.4
Name: flintai-cli
Version: 1.0.0
Summary: Command-line tool for evaluating agents, offering two features to assess agents via code scanning (`flintai scan`, whitebox testing) and runtime evaluation (`flintai eval`, blackbox testing)
Author-email: SandboxAQ <info@flintai.dev>
License: Software: Flint AI
        
        Copyright (c) 2026 SB Technology, Inc. dba SandboxAQ
        
        This software is licensed to you under the Apache 2.0 License as limited by
        the "Commons Clause" license condition below. The "Commons Clause" license
        condition has been modified from the original version to clarify that the
        "Common Clause" license condition also applies to any derivatives of the
        Software.
        
        
        "Commons Clause" License Condition v1.0, as modified below
        
        The Software is provided to you by the Licensor under the License, as defined
        below, subject to the following condition.
        
        Without limiting other conditions in the License, the grant of rights under the
        License will not include, and the License does not grant to you, the right to
        Sell the Software or any derivative of the Software.
        
        For purposes of the foregoing, "Sell" means practicing any or all of the rights
        granted to you under the License to provide to third parties, for a fee or
        other consideration (including without limitation fees for hosting or
        consulting/ support services related to the Software), a product or service
        whose value derives, entirely or substantially, from the functionality of the
        Software. Any license notice or attribution required by the License must also
        include this Commons Clause License Condition notice.
        
        
        Apache License Version 2.0, January 2004
        http://www.apache.org/licenses/
        
        
        TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
        
        1. Definitions.
        
        "License" shall mean the terms and conditions for use, reproduction, and
        distribution as defined by Sections 1 through 9 of this document.
        
        "Licensor" shall mean the copyright owner or entity authorized by the copyright
        owner that is granting the License.
        
        "Legal Entity" shall mean the union of the acting entity and all other entities
        that control, are controlled by, or are under common control with that entity.
        For the purposes of this definition, "control" means (i) the power, direct or
        indirect, to cause the direction or management of such entity, whether by
        contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the
        outstanding shares, or (iii) beneficial ownership of such entity.
        
        "You" (or "Your") shall mean an individual or Legal Entity exercising
        permissions granted by this License.
        
        "Source" form shall mean the preferred form for making modifications, including
        but not limited to software source code, documentation source, and
        configuration files.
        
        "Object" form shall mean any form resulting from mechanical transformation or
        translation of a Source form, including but not limited to compiled object code,
        generated documentation, and conversions to other media types.
        
        "Work" shall mean the work of authorship, whether in Source or Object form, made
        available under the License, as indicated by a copyright notice that is included
        in or attached to the work.
        
        "Derivative Works" shall mean any work, whether in Source or Object form, that
        is based on (or derived from) the Work and for which the editorial revisions,
        annotations, elaborations, or other modifications represent, as a whole, an
        original work of authorship. For the purposes of this License, Derivative Works
        shall not include works that remain separable from, or merely link (or bind by
        name) to the interfaces of, the Work and Derivative Works thereof.
        
        "Contribution" shall mean any work of authorship, including the original version
        of the Work and any modifications or additions thereto, that is intentionally
        submitted to Licensor for inclusion in the Work by the copyright owner or by an
        individual or Legal Entity authorized to submit on behalf of the copyright
        owner. For the purposes of this definition, "submitted" means any form of
        electronic, verbal, or written communication sent to the Licensor or its
        representatives, including but not limited to communication on electronic
        mailing lists, source code control systems, and issue tracking systems that are
        managed by, or on behalf of, the Licensor for the purpose of discussing and
        improving the Work, but excluding communication that is conspicuously marked or
        otherwise designated in writing by the copyright owner as "Not a Contribution."
        
        "Contributor" shall mean Licensor and any individual or Legal Entity on behalf
        of whom a Contribution has been received by Licensor and subsequently
        incorporated within the Work.
        
        2. Grant of Copyright License. Subject to the terms and conditions of this
        License, each Contributor hereby grants to You a perpetual, worldwide,
        non-exclusive, no-charge, royalty-free, irrevocable copyright license to
        reproduce, prepare Derivative Works of, publicly display, publicly perform,
        sublicense, and distribute the Work and such Derivative Works in Source or
        Object form.
        
        3. Grant of Patent License. Subject to the terms and conditions of this
        License, each Contributor hereby grants to You a perpetual, worldwide,
        non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this
        section) patent license to make, have made, use, offer to sell, sell, import,
        and otherwise transfer the Work, where such license applies only to those patent
        claims licensable by such Contributor that are necessarily infringed by their
        Contribution(s) alone or by combination of their Contribution(s) with the Work
        to which such Contribution(s) was submitted. If You institute patent litigation
        against any entity (including a cross-claim or counterclaim in a lawsuit)
        alleging that the Work or a Contribution incorporated within the Work
        constitutes direct or contributory patent infringement, then any patent licenses
        granted to You under this License for that Work shall terminate as of the date
        such litigation is filed.
        
        4. Redistribution. You may reproduce and distribute copies of the Work or
        Derivative Works thereof in any medium, with or without modifications, and in
        Source or Object form, provided that You meet the following conditions:
        
        (a) You must give any other recipients of the Work or Derivative Works a copy
        of this License; and
        
        (b) You must cause any modified files to carry prominent notices stating that
        You changed the files; and
        
        (c) You must retain, in the Source form of any Derivative Works that You
        distribute, all copyright, patent, trademark, and attribution notices from the
        Source form of the Work, excluding those notices that do not pertain to any part
        of the Derivative Works; and
        
        (d) If the Work includes a "NOTICE" text file as part of its distribution, then
        any Derivative Works that You distribute must include a readable copy of the
        attribution notices contained within such NOTICE file, excluding those notices
        that do not pertain to any part of the Derivative Works, in at least one of the
        following places: within a NOTICE text file distributed as part of the
        Derivative Works; within the Source form or documentation, if provided along
        with the Derivative Works; or, within a display generated by the Derivative
        Works, if and wherever such third-party notices normally appear. The contents of
        the NOTICE file are for informational purposes only and do not modify the
        License. You may add Your own attribution notices within Derivative Works that
        You distribute, alongside or as an addendum to the NOTICE text from the Work,
        provided that such additional attribution notices cannot be construed as
        modifying the License. You may add Your own copyright statement to Your
        modifications and may provide additional or different license terms and
        conditions for use, reproduction, or distribution of Your modifications, or for
        any such Derivative Works as a whole, provided Your use, reproduction, and
        distribution of the Work otherwise complies with the conditions stated in this
        License.
        
        5. Submission of Contributions. Unless You explicitly state otherwise, any
        Contribution intentionally submitted for inclusion in the Work by You to the
        Licensor shall be under the terms and conditions of this License, without any
        additional terms or conditions. Notwithstanding the above, nothing herein shall
        supersede or modify the terms of any separate license agreement you may have
        executed with Licensor regarding such Contributions.
        
        6. Trademarks. This License does not grant permission to use the trade names,
        trademarks, service marks, or product names of the Licensor, except as required
        for reasonable and customary use in describing the origin of the Work and
        reproducing the content of the NOTICE file.
        
        7. Disclaimer of Warranty. Unless required by applicable law or agreed to in
        writing, Licensor provides the Work (and each Contributor provides its
        Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
        KIND, either express or implied, including, without limitation, any warranties
        or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
        PARTICULAR PURPOSE. You are solely responsible for determining the
        appropriateness of using or redistributing the Work and assume any risks
        associated with Your exercise of permissions under this License.
        
        8. Limitation of Liability. In no event and under no legal theory, whether in
        tort (including negligence), contract, or otherwise, unless required by
        applicable law (such as deliberate and grossly negligent acts) or agreed to in
        writing, shall any Contributor be liable to You for damages, including any
        direct, indirect, special, incidental, or consequential damages of any character
        arising as a result of this License or out of the use or inability to use the
        Work (including but not limited to damages for loss of goodwill, work stoppage,
        computer failure or malfunction, or any and all other commercial damages or
        losses), even if such Contributor has been advised of the possibility of such
        damages.
        
        9. Accepting Warranty or Additional Liability. While redistributing the Work or
        Derivative Works thereof, You may choose to offer, and charge a fee for,
        acceptance of support, warranty, indemnity, or other liability obligations
        and/or rights consistent with this License. However, in accepting such
        obligations, You may act only on Your own behalf and on Your sole
        responsibility, not on behalf of any other Contributor, and only if You agree to
        indemnify, defend, and hold each Contributor harmless for any liability incurred
        by, or claims asserted against, such Contributor by reason of your accepting any
        such warranty or additional liability.
        
        END OF TERMS AND CONDITIONS
        
        
        APPENDIX: How to apply the Apache License to your work
        
        To apply the Apache License to your work, attach the following boilerplate
        notice, with the fields enclosed by brackets "[]" replaced with your own
        identifying information. (Don't include the brackets!) The text should be
        enclosed in the appropriate comment syntax for the file format. We also
        recommend that a file or class name and description of purpose be included on
        the same "printed page" as the copyright notice for easier identification
        within third-party archives.
        
        Copyright [yyyy] [name of copyright owner]
        
        Licensed under the Apache License, Version 2.0 (the "License"); you may not use
        this file except in compliance with the License. You may obtain a copy of the
        License at
        
        http://www.apache.org/licenses/LICENSE-2.0
        
        Unless required by applicable law or agreed to in writing, software distributed
        under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
        CONDITIONS OF ANY KIND, either express or implied. See the License for the
        specific language governing permissions and limitations under the License.
        
Project-URL: Homepage, https://github.com/sandbox-quantum/flintai-cli
Project-URL: Issues, https://github.com/sandbox-quantum/flintai-cli/issues
Requires-Python: >=3.13
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: aiohttp>=3.9
Requires-Dist: anthropic==0.87.0
Requires-Dist: cvss>=2.6
Requires-Dist: datafog>=4.4.0
Requires-Dist: dataclasses-json==0.6.7
Requires-Dist: detect-secrets>=1.5.0
Requires-Dist: garak==0.14.0
Requires-Dist: google-adk==2.2.0
Requires-Dist: litellm>=1.83.7
Requires-Dist: openai==2.29.0
Requires-Dist: pydantic==2.12.5
Requires-Dist: python-dotenv==1.2.2
Requires-Dist: requests>=2.33.0
Requires-Dist: rich>=13.0
Requires-Dist: transformers==5.3.0
Dynamic: license-file

<div align="center">

<img src="images/flint-ai-wordmark.svg" alt="Flint AI" width="350">

[![PyPI version](https://img.shields.io/pypi/v/flintai-cli?color=A1C9D2&logo=pypi&logoColor=white)](https://pypi.org/project/flintai-cli/) [![Python](https://img.shields.io/badge/python-3.13+-A1C9D2?logo=python&logoColor=white)](https://www.python.org/downloads/) [![License](https://img.shields.io/github/license/sandbox-quantum/flintai-cli?color=1B1817&labelColor=555&logoColor=white)](https://github.com/sandbox-quantum/flintai-cli/blob/main/LICENSE) [![Documentation](https://img.shields.io/badge/docs-docs.flintai.dev-FF895E)](https://docs.flintai.dev) [![Website](https://img.shields.io/badge/website-flintai.dev-FF895E)](https://flintai.dev)

</div>

**Ship AI agents with confidence**

One CLI to analyze agent code and runtime behavior, any framework.

| | **Flint AI Scan** | **Flint AI Eval** |
|---|---|---|
| **Command** | `flintai scan` | `flintai eval` |
| **What** | AI-powered security analysis of your agent's code (whitebox testing) | Runtime behavioral evaluation with adversarial prompts (blackbox testing) |
| **Output** | Security findings mapped to OWASP Top 10 for LLM with CVSS severity scores  | Evaluation scores (0-100%) mapped to OWASP Top 10 for LLM  |

**Why Flint AI?**
- **AI-powered analysis** — Contextual code understanding, not just pattern matching
- **OWASP ASI mapped** — Findings aligned to Top 10 for Agentic Applications  
- **100% free** — First results in minutes


## Try it now - 5 minute Quickstart

> **Requirements**  
> - Python 3.13 or later  
> - [OpenGrep](https://github.com/opengrep/opengrep#linux--macos) (required for Flint AI Scan)
> - A running agent accessible via HTTP (required for Flint AI Eval)
> 
> **Supported frameworks:** Google ADK, Google GenAI, Anthropic, OpenAI, OpenAI Agents SDK, LangGraph, CrewAI, AutoGen, HuggingFace Transformers, HuggingFace smolagents

### Step 1: Install Flint AI

```bash
pip install flintai-cli
```

### Step 2: Configure your LLM provider

Flint AI uses AI to analyze agent code and score reliability. Run the interactive setup:

```bash
flintai init
```

You'll be prompted to select a provider (Gemini, OpenAI, Anthropic, or LiteLLM), choose a model, and enter your API key.

<details>
<summary>Where to get API keys</summary>

- **Google Gemini**: [aistudio.google.com/apikey](https://aistudio.google.com/apikey) (free tier available)
- **OpenAI**: [platform.openai.com/api-keys](https://platform.openai.com/api-keys)
- **Anthropic**: [console.anthropic.com/settings/keys](https://console.anthropic.com/settings/keys)
- **LiteLLM**: Supports 100+ providers. See [docs.litellm.ai](https://docs.litellm.ai/docs/)

</details>

> Run into issues? See [installation troubleshooting](https://docs.flintai.dev/troubleshooting/common-issues#installation)

### Step 3: Try the example agents

To demonstrate the CLIs capabilities, we've shipped this tool with two example agents. You can get them [here](https://github.com/sandbox-quantum/flintai-cli/tree/main/examples).

**Both agents work with both `flintai scan` and `flintai eval`**:

| Agent | Framework | Description |
|-------|-----------|-------------|
| **weather_agent** | Google ADK | Weather assistant that looks up conditions for cities. Should refuse off-topic requests. |
| **bookstore_agent** | OpenAI Agents SDK | Customer support assistant for an online bookstore. Searches books, checks orders, and processes returns. |

The included `examples/config.json` has both agents configured with builtin evaluations (OWASP LLM01–LLM09, PII, secrets) and custom tests.

--- 

`flintai scan` finds security issues in the code without running the agent. We'll scan the bookstore agent to see what issues Flint AI can find:
```bash
flintai scan examples/bookstore_agent/
```

<img src="images/scan-findings.png" alt="Scan results showing security findings" width="550">

*Example: Scan found 2 security issues - High severity missing authentication and Medium severity unbounded execution loop*

---

`flintai eval` tests runtime behavior, so the agent needs to be running. Start the bookstore agent:

```bash
# Start the bookstore agent (serves on http://localhost:8010)
uvx --with openai-agents,fastapi --from uvicorn uvicorn examples.bookstore_agent.agent:app --port 8010 --host 0.0.0.0
```

In a new terminal, run evaluations:

```bash
flintai eval run --model model-bookstore-agent --config examples/config.json
```

### Step 4: Test your own agents

See our documentation to configure, scan and evaluate your agents:
- `flintai scan`
  - [Scan your own agent](https://docs.flintai.dev/scan/getting-started) — Apply Flint AI Scan to your codebase
  - [Understand scan results](https://docs.flintai.dev/scan/scan-results) — Interpret findings and severity scores
- `flintai eval`
  - [Evaluate your own agent](https://docs.flintai.dev/eval/getting-started) — Configure and test your agent's behavior
  - [Configuration](https://docs.flintai.dev/eval/getting-started) — In-depth documentation of our configuration
  - [Understand eval results](https://docs.flintai.dev/eval/eval-results) — What the scores means and how to improve

**Ship with confidence.** Validate behavior, catch risks, prove readiness.


## Commands

### `init`

Setup wizard that configures Flint AI for first use. Creates the `~/.flintai` directory with a `.env` file (LLM provider, API key, runtime settings) and a `config.json` skeleton.

Runs automatically on first use in non-CI environments. You can re-run it at any time to reconfigure.

```bash
flintai init
```

### `scan`

AI-powered security analysis of agent source code. Finds vulnerabilities, misconfigurations, and OWASP Top 10 violations.

```bash
# Scan a directory
flintai scan /path/to/agent/code

# Scan a single file
flintai scan agent.py

# Specify output file
flintai scan /path/to/code --output results.json
```

[Full scan guide](https://docs.flintai.dev/scan/getting-started)

### `eval`

Test agent behavior at runtime. Get a evaluation score proving production-readiness.

```bash
# List all available configuration
flintai eval evaluations list

# List your agents and models
flintai eval models list

# Attach an evalation to your agent
flintai eval model-evaluations attach \
  --model my-agent \
  --eval eval-llm01-adversarial

# Run all evaluations for an agent
flintai eval run --model my-agent
```

The `flintai eval` command requires configuration. See [Configuration](https://docs.flintai.dev/eval/eval-configuration) to:
1. Define your models (agents to test)
2. View available evaluations
3. Attach evaluations to models

[Full eval guide](https://docs.flintai.dev/eval/getting-started)

## Documentation

**Complete guides and reference:**
- [Getting started](https://docs.flintai.dev)
- [Scan command reference](https://docs.flintai.dev/scan/scan-command)
- [Eval command reference](https://docs.flintai.dev/eval/eval-command)
- [Configuration](https://docs.flintai.dev/eval/eval-configuration)
- [Environment variables](https://docs.flintai.dev/reference/env-vars)
- [Built-in evaluations](https://docs.flintai.dev/reference/builtin-evaluations)
- [Data privacy](https://docs.flintai.dev/reference/data-privacy)
- [FAQ](https://docs.flintai.dev/resources/faq)

## Data privacy

Flint AI runs on your machine, but several features can call external LLM providers. This can be configured via `GENERATOR_MODEL` 
(located in `~/.flintai/.env`, created by `flintai init`). You can set this to a remote managed LLM (i.e. `gemini`, `openai`, `anthropic`)
or a locally hosted LLM (i.e. `litellm` or `ollama`).

[Read more](https://docs.flintai.dev/reference/data-privacy).

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for details.

## License

Free to use - [full license](LICENSE).

## Contact

- Website: [https://flintai.dev](https://flintai.dev)
- Email: [info@flintai.dev](mailto:info@flintai.dev)


