Metadata-Version: 2.5
Name: corax-cli
Version: 1.0.0
Summary: CLI for Corax AI backend
Author-email: Trifork Corax AI Team <corax-ai@trifork.com>
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: keyring>=25.6.0
Requires-Dist: platformdirs>=4.3.0
Requires-Dist: rich>=13.9.0
Requires-Dist: typer>=0.16.0
Description-Content-Type: text/markdown

# corax-cli

Agent-first CLI for interacting with Corax AI backend APIs.

## Quickstart

```bash
uv sync --dev
uv run corax --help
```

## Global Installation

Install the `corax` command globally so it's available from any directory:

```bash
uv tool install -e .
```

To uninstall:

```bash
uv tool uninstall corax-cli
```

## Installing A Released Version (PyPI)

Released versions are published to PyPI:

```bash
uv tool install corax-cli
# or: pip install corax-cli
```

To uninstall:

```bash
uv tool uninstall corax-cli
```

## Defaults

- Default output is `json`.
- Global output flags must appear before the subcommand.
- Use `--output text|table|tsv` when you explicitly want human-oriented output.
- Use `--select <dot.path>` to extract a single field from structured output.

Examples:

```bash
uv run corax project list
uv run corax --output text project list
uv run corax --select body._embedded.0.id project list
```

## Common Flow

```bash
uv run corax env list
uv run corax env use local
printf '%s' "$CORAX_API_KEY" | uv run corax auth api-key set --env local --value-stdin
uv run corax doctor
uv run corax project create --name "My Project" --description "CLI created"
uv run corax capability create --name "My Chat Capability" --type chat --system-prompt "You are helpful."
uv run corax capability execute <capability-id> --message "Hello"
```

## Migration Note

- The `smoke` command has been removed.
- For connectivity and auth checks, use `uv run corax doctor --env <env>`.
- For broader live verification, compose the normal resource commands directly:
  `project create`, `capability create`, `capability execute`, `execution wait`, and cleanup with `delete`.

## Environment And Auth

Non-interactive only:

```bash
uv run corax env create staging https://staging.example.com --verify-ssl
uv run corax env update staging --base-url https://staging-v2.example.com
printf '%s' "$CORAX_API_KEY" | uv run corax env update staging --api-key-stdin
uv run corax env delete staging --yes
```

```bash
printf '%s' "$CORAX_API_KEY" | uv run corax auth api-key set --env local --value-stdin
printf '%s' "$CORAX_BEARER_TOKEN" | uv run corax auth bearer-token set --env local --value-stdin
uv run corax auth token resolve
uv run corax auth token resolve --header
```

## Capability Execution

```bash
uv run corax capability execute <capability-id> --message "Hello"
uv run corax capability execute <capability-id> --message "Hello" --wait
uv run corax capability execute <capability-id> --message "Hello" --stream
```

Structured payloads:

```bash
uv run corax capability execute <capability-id> --payload-json '{"message":"Hello"}'
cat payload.json | uv run corax capability execute <capability-id> --payload-json @-
```

## Streaming

Structured output is line-delimited JSON-friendly by default:

```bash
uv run corax capability execute <capability-id> --message "Hello" --stream
uv run corax execution stream <capability-id> <execution-id>
```

Use text mode for interactive reading:

```bash
uv run corax --output text capability execute <capability-id> --message "Hello" --stream
```

## Waiting And Inspection

```bash
uv run corax execution list <capability-id>
uv run corax execution get <capability-id> <execution-id>
uv run corax execution result <capability-id> <execution-id>
uv run corax execution usage <capability-id> <execution-id>
uv run corax execution wait <capability-id> <execution-id>
```

## Generic API Discovery

```bash
uv run corax api list
uv run corax api search capabilities
uv run corax api show /v1/projects
uv run corax api request GET /v1/projects
cat body.json | uv run corax api request POST /v1/projects --json @- --yes
```

## Projects And Capabilities

```bash
uv run corax project list
uv run corax project create --name "Research" --description "RAG experiments" --private
uv run corax project get <project-id>
uv run corax project update <project-id> --json '{"name":"Research","description":"Updated","is_public":false}'
uv run corax project delete <project-id> --yes
```

```bash
uv run corax capability list
uv run corax capability get <capability-id>
uv run corax capability create --name "My Completion Capability" --type completion --system-prompt "You are concise." --completion-prompt "User says: {user_input}"
uv run corax capability patch <capability-id> --json '{"system_prompt":"Updated"}' --yes
uv run corax capability delete <capability-id> --yes
```

## Capability Diffs

Default output is structured JSON:

```bash
uv run corax capability diff <capability-id> --from 1 --to 2
```

Use text mode for review output:

```bash
uv run corax --output text capability diff <capability-id> --from 1 --to 2
uv run corax --output text capability diff <capability-id> --from 1 --to 2 --prompts
uv run corax --output text capability diff <capability-id> --from 1 --to 2 --prompts --field system_prompt
uv run corax --output text capability diff <capability-id> --from 1 --to 2 --delta
```

Render and write files:

```bash
uv run corax --output text capability diff <capability-id> --from 1 --to 2 \
  --view prompts-markdown \
  --write-files /tmp/corax-diff
```
