fulfil-cli 0.1.3__tar.gz → 0.2.0__tar.gz

{fulfil_cli-0.1.3 → fulfil_cli-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: fulfil-cli
-Version: 0.1.3
+Version: 0.2.0
 Summary: The Fulfil CLI — primary interface for humans and AI agents
 Keywords: fulfil,cli,erp,ecommerce
 Author: Fulfil.IO
@@ -108,12 +108,12 @@ fulfil sales_order list --fields reference,state,total_amount
 
 # Filter with MongoDB-style queries
 fulfil sales_order list --where '{"state": "confirmed"}'
-fulfil sales_order list --where '{"total_amount": {"gte": 1000}}'
+fulfil sales_order list --where '{"sale_date": {"gte": "2025-01-01"}}'
 fulfil sales_order list --where '{"or": [{"state": "draft"}, {"state": "confirmed"}]}'
 
 # Sort results
 fulfil sales_order list --order sale_date:desc
-fulfil sales_order list --order total_amount:desc,reference:asc
+fulfil sales_order list --order sale_date:desc,reference:asc
 
 # Control page size
 fulfil sales_order list --limit 50
@@ -134,20 +134,23 @@ fulfil sales_order get 1,2,3
 ### Creating records
 
 ```bash
-# Single record
-fulfil contact create --data '{"name": "Acme Corp"}'
+# Single record (from stdin)
+echo '{"name": "Acme Corp"}' | fulfil contact create
 
 # Record with nested lines (e.g. contact with addresses)
-fulfil contact create --data '{"name": "Acme Corp", "addresses": [{"street": "100 Broadway", "city": "New York"}, {"street": "45 Industrial Pkwy", "city": "Newark"}]}'
+echo '{"name": "Acme Corp", "addresses": [{"street": "100 Broadway", "city": "New York"}, {"street": "45 Industrial Pkwy", "city": "Newark"}]}' | fulfil contact create
 
-# Multiple records at once
-fulfil contact create --data '[{"name": "Alice"}, {"name": "Bob"}]'
+# Multiple records at once (preferred — never loop single creates)
+echo '[{"name": "Alice"}, {"name": "Bob"}]' | fulfil contact create
+
+# From a file
+fulfil contact create data.json
 ```
 
 ### Updating records
 
 ```bash
-fulfil sales_order update 42 --data '{"comment": "Approved by finance"}'
+echo '{"comment": "Approved by finance"}' | fulfil sales_order update 42
 ```
 
 ### Deleting records
@@ -218,14 +221,17 @@ echo '{"method": "model.product.count", "params": {}}' | fulfil api -
 |---|---|
 | Terminal | Rich tables with colors |
 | Piped / redirected / CI | JSON (automatic) |
-| `--json` flag | JSON (forced) |
+| `--format` flag | table, json, csv, or ndjson |
 
 ```bash
 # Force JSON and pipe to jq
-fulfil sales_order list --fields reference,state --json | jq '.data[].reference'
+fulfil sales_order list --fields reference,state --format json | jq '.data[].reference'
+
+# Force format via env var
+FULFIL_FORMAT=json fulfil sales_order list
 
-# Force JSON via env var
-FULFIL_JSON=1 fulfil sales_order list
+# CSV output
+fulfil sales_order list --fields reference,state --format csv
 ```
 
 ## Configuration
@@ -245,7 +251,7 @@ Config file location: `~/.config/fulfil/config.toml`
 --workspace TEXT    Workspace domain (e.g. acme.fulfil.io)
 --debug            Show HTTP request/response details
 --quiet, -q        Suppress hints and decorative output
---json             Force JSON output
+--format TEXT      Output format: table, json, csv, ndjson
 -h, --help         Show help
 ```
 
@@ -274,7 +280,7 @@ fulfil completion   # auto-detects zsh/bash/fish
 
 The CLI is designed for programmatic use:
 
-- **JSON output by default** when stdout is piped or redirected
+- **JSON output by default** when stdout is piped or redirected (override with `--format` or `FULFIL_FORMAT`)
 - **Structured exit codes** for error handling
 - **Errors on stderr**, data on stdout — safe to parse stdout directly
 - **Environment variable auth** — no interactive prompts: `FULFIL_API_KEY` + `FULFIL_WORKSPACE`

{fulfil_cli-0.1.3 → fulfil_cli-0.2.0}/README.md

@@ -78,12 +78,12 @@ fulfil sales_order list --fields reference,state,total_amount
 
 # Filter with MongoDB-style queries
 fulfil sales_order list --where '{"state": "confirmed"}'
-fulfil sales_order list --where '{"total_amount": {"gte": 1000}}'
+fulfil sales_order list --where '{"sale_date": {"gte": "2025-01-01"}}'
 fulfil sales_order list --where '{"or": [{"state": "draft"}, {"state": "confirmed"}]}'
 
 # Sort results
 fulfil sales_order list --order sale_date:desc
-fulfil sales_order list --order total_amount:desc,reference:asc
+fulfil sales_order list --order sale_date:desc,reference:asc
 
 # Control page size
 fulfil sales_order list --limit 50
@@ -104,20 +104,23 @@ fulfil sales_order get 1,2,3
 ### Creating records
 
 ```bash
-# Single record
-fulfil contact create --data '{"name": "Acme Corp"}'
+# Single record (from stdin)
+echo '{"name": "Acme Corp"}' | fulfil contact create
 
 # Record with nested lines (e.g. contact with addresses)
-fulfil contact create --data '{"name": "Acme Corp", "addresses": [{"street": "100 Broadway", "city": "New York"}, {"street": "45 Industrial Pkwy", "city": "Newark"}]}'
+echo '{"name": "Acme Corp", "addresses": [{"street": "100 Broadway", "city": "New York"}, {"street": "45 Industrial Pkwy", "city": "Newark"}]}' | fulfil contact create
 
-# Multiple records at once
-fulfil contact create --data '[{"name": "Alice"}, {"name": "Bob"}]'
+# Multiple records at once (preferred — never loop single creates)
+echo '[{"name": "Alice"}, {"name": "Bob"}]' | fulfil contact create
+
+# From a file
+fulfil contact create data.json
 ```
 
 ### Updating records
 
 ```bash
-fulfil sales_order update 42 --data '{"comment": "Approved by finance"}'
+echo '{"comment": "Approved by finance"}' | fulfil sales_order update 42
 ```
 
 ### Deleting records
@@ -188,14 +191,17 @@ echo '{"method": "model.product.count", "params": {}}' | fulfil api -
 |---|---|
 | Terminal | Rich tables with colors |
 | Piped / redirected / CI | JSON (automatic) |
-| `--json` flag | JSON (forced) |
+| `--format` flag | table, json, csv, or ndjson |
 
 ```bash
 # Force JSON and pipe to jq
-fulfil sales_order list --fields reference,state --json | jq '.data[].reference'
+fulfil sales_order list --fields reference,state --format json | jq '.data[].reference'
+
+# Force format via env var
+FULFIL_FORMAT=json fulfil sales_order list
 
-# Force JSON via env var
-FULFIL_JSON=1 fulfil sales_order list
+# CSV output
+fulfil sales_order list --fields reference,state --format csv
 ```
 
 ## Configuration
@@ -215,7 +221,7 @@ Config file location: `~/.config/fulfil/config.toml`
 --workspace TEXT    Workspace domain (e.g. acme.fulfil.io)
 --debug            Show HTTP request/response details
 --quiet, -q        Suppress hints and decorative output
---json             Force JSON output
+--format TEXT      Output format: table, json, csv, ndjson
 -h, --help         Show help
 ```
 
@@ -244,7 +250,7 @@ fulfil completion   # auto-detects zsh/bash/fish
 
 The CLI is designed for programmatic use:
 
-- **JSON output by default** when stdout is piped or redirected
+- **JSON output by default** when stdout is piped or redirected (override with `--format` or `FULFIL_FORMAT`)
 - **Structured exit codes** for error handling
 - **Errors on stderr**, data on stdout — safe to parse stdout directly
 - **Environment variable auth** — no interactive prompts: `FULFIL_API_KEY` + `FULFIL_WORKSPACE`

{fulfil_cli-0.1.3 → fulfil_cli-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "fulfil-cli"
-version = "0.1.3"
+version = "0.2.0"
 description = "The Fulfil CLI — primary interface for humans and AI agents"
 readme = "README.md"
 requires-python = ">=3.10"

fulfil_cli-0.2.0/src/fulfil_cli/__init__.py

@@ -0,0 +1,6 @@
+"""Fulfil CLI — command-line interface for the Fulfil ERP platform."""
+
+from importlib.metadata import version
+
+__version__ = version("fulfil-cli")
+__all__ = ["__version__"]

fulfil_cli-0.2.0/src/fulfil_cli/auth/__init__.py

@@ -0,0 +1,3 @@
+from fulfil_cli.auth.api_key import Credentials, normalize_workspace, resolve_credentials
+
+__all__ = ["Credentials", "normalize_workspace", "resolve_credentials"]

{fulfil_cli-0.1.3 → fulfil_cli-0.2.0}/src/fulfil_cli/auth/api_key.py

@@ -1,11 +1,13 @@
-"""API key resolution — env > flag > keyring."""
+"""Credential resolution — flag > env > keyring, with workspace normalization."""
 
 from __future__ import annotations
 
 import os
 from dataclasses import dataclass
+from typing import Literal
 
 from fulfil_cli.auth.keyring_store import get_api_key, get_oauth_tokens, store_oauth_tokens
+from fulfil_cli.auth.oauth import OAuthTokens, discover_oidc, refresh_access_token
 from fulfil_cli.client.errors import AuthError
 
 
@@ -13,42 +15,12 @@ from fulfil_cli.client.errors import AuthError
 class Credentials:
     """Resolved authentication credentials."""
 
-    method: str  # "api_key" or "oauth"
+    method: Literal["api_key", "oauth"]
     api_key: str | None = None
     access_token: str | None = None
     workspace: str | None = None
 
 
-def resolve_api_key(
-    *,
-    token_flag: str | None = None,
-    workspace: str | None = None,
-) -> str:
-    """Resolve API key from: --token flag > FULFIL_API_KEY env > keyring.
-
-    Raises AuthError if no key can be found.
-    """
-    # 1. Explicit --token flag
-    if token_flag:
-        return token_flag
-
-    # 2. Environment variable
-    env_key = os.environ.get("FULFIL_API_KEY")
-    if env_key:
-        return env_key
-
-    # 3. Keyring (requires workspace)
-    if workspace:
-        stored = get_api_key(workspace)
-        if stored:
-            return stored
-
-    raise AuthError(
-        message="No API key found",
-        hint="Run 'fulfil auth login' or set FULFIL_API_KEY environment variable.",
-    )
-
-
 def resolve_credentials(
     *,
     token_flag: str | None = None,
@@ -57,23 +29,18 @@ def resolve_credentials(
 ) -> Credentials:
     """Resolve credentials, supporting both API key and OAuth.
 
-    Priority: --token flag → FULFIL_API_KEY env → check auth method → keyring.
+    Priority: --token flag > FULFIL_API_KEY env > check auth method > keyring.
     """
-    # 1. Explicit --token flag (always treated as API key)
     if token_flag:
         return Credentials(method="api_key", api_key=token_flag)
 
-    # 2. Environment variable
     env_key = os.environ.get("FULFIL_API_KEY")
     if env_key:
         return Credentials(method="api_key", api_key=env_key)
 
-    # 3. Based on configured auth method
     if auth_method == "oauth" and workspace:
         tokens_json = get_oauth_tokens(workspace)
         if tokens_json:
-            from fulfil_cli.auth.oauth import OAuthTokens, discover_oidc, refresh_access_token
-
             tokens = OAuthTokens.from_json(tokens_json)
             if tokens.is_expired and tokens.refresh_token:
                 oidc = discover_oidc(workspace)
@@ -85,7 +52,6 @@ def resolve_credentials(
                 workspace=workspace,
             )
 
-    # 4. Fall back to API key from keyring
     if workspace:
         stored = get_api_key(workspace)
         if stored:
@@ -108,11 +74,11 @@ def resolve_workspace(
     Raises AuthError if no workspace can be found.
     """
     if workspace_flag:
-        return _normalize_workspace(workspace_flag)
+        return normalize_workspace(workspace_flag)
 
     env_workspace = os.environ.get("FULFIL_WORKSPACE")
     if env_workspace:
-        return _normalize_workspace(env_workspace)
+        return normalize_workspace(env_workspace)
 
     if config_workspace:
         return config_workspace
@@ -123,7 +89,7 @@ def resolve_workspace(
     )
 
 
-def _normalize_workspace(value: str) -> str:
+def normalize_workspace(value: str) -> str:
     """Normalize workspace input — accept slug or full domain.
 
     'acme' → 'acme.fulfil.io'

{fulfil_cli-0.1.3 → fulfil_cli-0.2.0}/src/fulfil_cli/cli/app.py

@@ -1,4 +1,12 @@
-"""Root CLI application with dynamic model subcommands."""
+"""Root CLI application with dynamic model and report subcommands.
+
+Typer handles the root app and static commands (auth, config, version)
+where type-driven argument parsing shines. Click groups are used for
+dynamic model and report routing because Typer does not support runtime
+subcommand creation via ``get_command`` overrides — the ``FulfilGroup``
+and ``ReportGroup`` classes intercept unknown subcommand names and
+resolve them as Fulfil model or report names respectively.
+"""
 
 from __future__ import annotations
 
@@ -10,24 +18,17 @@ from rich.console import Console
 from fulfil_cli import __version__
 from fulfil_cli.cli.commands import auth, config
 from fulfil_cli.cli.commands.api import api_cmd
+from fulfil_cli.cli.commands.common import handle_error
 from fulfil_cli.cli.commands.completion import completion_install
 from fulfil_cli.cli.commands.model import create_model_group
 from fulfil_cli.cli.commands.report import create_report_group
-from fulfil_cli.cli.state import get_client, is_quiet, set_globals
-from fulfil_cli.client.errors import FulfilError
+from fulfil_cli.cli.state import VALID_FORMATS, AppContext, format_option
+from fulfil_cli.client.errors import EXIT_USAGE, FulfilError
 from fulfil_cli.output.formatter import output
 
 console = Console(stderr=True)
 
 
-def _handle_error(exc: FulfilError) -> None:
-    """Print error and exit with appropriate code."""
-    console.print(f"[red]Error: {exc}[/red]")
-    if exc.hint and not is_quiet():
-        console.print(f"[dim]Hint: {exc.hint}[/dim]")
-    raise typer.Exit(code=exc.exit_code)
-
-
 class ReportGroup(click.Group):
     """Click group that resolves unknown subcommands as report names."""
 
@@ -41,7 +42,6 @@ class ReportGroup(click.Group):
 class FulfilGroup(typer.core.TyperGroup):
     """Custom Click group that resolves unknown subcommands as model or report names."""
 
-    # Dynamic commands that should appear in help alongside static ones
     _dynamic_commands = ("models", "reports")
 
     def list_commands(self, ctx: click.Context) -> list[str]:
@@ -52,17 +52,13 @@ class FulfilGroup(typer.core.TyperGroup):
         return commands
 
     def get_command(self, ctx: click.Context, cmd_name: str) -> click.Command | None:
-        # Check static commands first
         rv = super().get_command(ctx, cmd_name)
         if rv is not None:
             return rv
-        # `fulfil models` / `fulfil models list`
         if cmd_name == "models":
             return models_group
-        # `fulfil reports` / `fulfil reports list` / `fulfil reports <name> execute`
         if cmd_name == "reports":
             return reports_group
-        # Treat as model name → return model sub-group
         return create_model_group(cmd_name)
 
 
@@ -113,34 +109,64 @@ def main_callback(
     base_url: str | None = typer.Option(None, "--base-url", hidden=True, help="Override base URL"),
     debug: bool = typer.Option(False, "--debug", help="Show debug output"),
     quiet: bool = typer.Option(False, "--quiet", "-q", help="Suppress hints and decorative output"),
+    output_format: str | None = typer.Option(
+        None,
+        "--format",
+        help="Output format: table, json, csv, ndjson (default: table for TTY, json when piped)",
+    ),
 ) -> None:
     """Root callback — sets global auth state."""
-    set_globals(token=token, workspace=workspace, base_url=base_url, debug=debug, quiet=quiet)
+    if output_format and output_format not in VALID_FORMATS:
+        console.print(
+            f"[red]Error: Invalid format '{output_format}'. "
+            f"Choose from: {', '.join(VALID_FORMATS)}[/red]"
+        )
+        raise typer.Exit(code=EXIT_USAGE)
+    ctx.obj = AppContext(
+        token=token,
+        workspace=workspace,
+        base_url=base_url,
+        debug=debug,
+        quiet=quiet,
+        output_format=output_format,
+    )
+
+
+FORMAT_OPTION = typer.Option(
+    None,
+    "--format",
+    help="Output format: table, json, csv, ndjson",
+)
 
 
 @app.command()
 def version(
-    json_flag: bool = typer.Option(False, "--json", help="Output as JSON"),
+    ctx: typer.Context,
+    output_format: str | None = FORMAT_OPTION,
 ) -> None:
     """Show CLI version."""
-    if json_flag:
-        output({"version": __version__}, json_flag=True)
-    else:
+    app_ctx: AppContext = ctx.obj
+    fmt = app_ctx.get_effective_format(output_format)
+    if fmt == "table":
         typer.echo(f"fulfil-cli {__version__}")
+    else:
+        output({"version": __version__}, fmt=fmt)
 
 
 @app.command()
 def whoami(
-    json_flag: bool = typer.Option(False, "--json", help="Output as JSON"),
+    ctx: typer.Context,
+    output_format: str | None = FORMAT_OPTION,
 ) -> None:
     """Show current user and workspace info."""
+    app_ctx: AppContext = ctx.obj
     try:
-        client = get_client()
+        client = app_ctx.get_client()
         result = client.call("system.whoami")
     except FulfilError as exc:
-        _handle_error(exc)
+        handle_error(exc)
 
-    output(result, json_flag=json_flag)
+    output(result, fmt=app_ctx.get_effective_format(output_format))
 
 
 def _flatten_model_row(row: dict) -> dict:
@@ -157,13 +183,14 @@ def _flatten_model_row(row: dict) -> dict:
     }
 
 
-def _list_models(json_flag: bool, search: str | None = None) -> None:
+def _list_models(fmt: str, search: str | None = None) -> None:
     """Fetch and display all available models."""
+    app_ctx: AppContext = click.get_current_context().obj
     try:
-        client = get_client()
+        client = app_ctx.get_client()
         result = client.call("system.list_models")
     except FulfilError as exc:
-        _handle_error(exc)
+        handle_error(exc)
 
     if search and isinstance(result, list):
         term = search.lower()
@@ -178,43 +205,43 @@ def _list_models(json_flag: bool, search: str | None = None) -> None:
             )
         ]
 
-    if not json_flag and isinstance(result, list):
+    if fmt == "table" and isinstance(result, list):
         result = [_flatten_model_row(r) for r in result if isinstance(r, dict)]
 
-    output(result, json_flag=json_flag, title="Available Models")
+    output(result, fmt=fmt, title="Available Models")
 
 
 @click.group(name="models", help="List available models.", invoke_without_command=True)
-@click.option("--json", "json_flag", is_flag=True, help="Output as JSON")
 @click.option("--search", "-s", default=None, help="Filter by name, description, or category.")
+@format_option
 @click.pass_context
-def models_group(ctx: click.Context, json_flag: bool, search: str | None) -> None:
+def models_group(ctx: click.Context, search: str | None, output_format: str | None) -> None:
     """List all available models."""
-    ctx.ensure_object(dict)
-    ctx.obj["json_flag"] = json_flag
-    ctx.obj["search"] = search
     if ctx.invoked_subcommand is None:
-        _list_models(json_flag, search=search)
+        app_ctx: AppContext = ctx.obj
+        _list_models(app_ctx.get_effective_format(output_format), search=search)
 
 
 @models_group.command("list")
-@click.option("--json", "json_flag", is_flag=True, help="Output as JSON")
 @click.option("--search", "-s", default=None, help="Filter by name, description, or category.")
+@format_option
 @click.pass_context
-def models_list_cmd(ctx: click.Context, json_flag: bool, search: str | None) -> None:
+def models_list_cmd(ctx: click.Context, search: str | None, output_format: str | None) -> None:
     """List all available models."""
-    _list_models(json_flag, search=search)
+    app_ctx: AppContext = ctx.obj
+    _list_models(app_ctx.get_effective_format(output_format), search=search)
 
 
-def _list_reports(json_flag: bool) -> None:
+def _list_reports(fmt: str) -> None:
     """Fetch and display all available reports."""
+    app_ctx: AppContext = click.get_current_context().obj
     try:
-        client = get_client()
+        client = app_ctx.get_client()
         result = client.call("system.list_reports")
     except FulfilError as exc:
-        _handle_error(exc)
+        handle_error(exc)
 
-    output(result, json_flag=json_flag, title="Available Reports")
+    output(result, fmt=fmt, title="Available Reports")
 
 
 @click.group(
@@ -223,42 +250,46 @@ def _list_reports(json_flag: bool) -> None:
     help="Interact with reports.",
     invoke_without_command=True,
 )
-@click.option("--json", "json_flag", is_flag=True, help="Output as JSON")
+@format_option
 @click.pass_context
-def reports_group(ctx: click.Context, json_flag: bool) -> None:
+def reports_group(ctx: click.Context, output_format: str | None) -> None:
     """List all available reports."""
-    ctx.ensure_object(dict)
-    ctx.obj["json_flag"] = json_flag
     if ctx.invoked_subcommand is None:
-        _list_reports(json_flag)
+        app_ctx: AppContext = ctx.obj
+        _list_reports(app_ctx.get_effective_format(output_format))
 
 
 @reports_group.command("list")
-@click.option("--json", "json_flag", is_flag=True, help="Output as JSON")
+@format_option
 @click.pass_context
-def reports_list_cmd(ctx: click.Context, json_flag: bool) -> None:
+def reports_list_cmd(ctx: click.Context, output_format: str | None) -> None:
     """List all available reports."""
-    _list_reports(json_flag)
+    app_ctx: AppContext = ctx.obj
+    _list_reports(app_ctx.get_effective_format(output_format))
 
 
 @app.command()
 def docs(
+    ctx: typer.Context,
     query: str = typer.Argument(..., help="Search query for Fulfil documentation"),
-    json_flag: bool = typer.Option(False, "--json", help="Output as JSON"),
+    output_format: str | None = FORMAT_OPTION,
 ) -> None:
     """Search Fulfil documentation."""
+    app_ctx: AppContext = ctx.obj
     try:
-        client = get_client()
+        client = app_ctx.get_client()
         results = client.call("system.search_docs", query=query)
     except FulfilError as exc:
-        _handle_error(exc)
+        handle_error(exc)
 
     if not results:
-        console.print("[dim]No results found.[/dim]")
+        if not app_ctx.quiet:
+            console.print("[dim]No results found.[/dim]")
         raise typer.Exit()
 
-    if json_flag:
-        output(results, json_flag=True)
+    fmt = app_ctx.get_effective_format(output_format)
+    if fmt != "table":
+        output(results, fmt=fmt)
     else:
         from rich.markdown import Markdown
         from rich.panel import Panel
@@ -315,8 +346,8 @@ fulfil sales_order get 42
 ## 4. Create and update records
 
 ```
-fulfil contact create --data '{"name": "Acme Corp"}'
-fulfil sales_order update 42 --data '{"comment": "Approved"}'
+echo '{"name": "Acme Corp"}' | fulfil contact create
+fulfil sales_order update 42 updates.json
 ```
 
 ## 5. Call workflow methods
@@ -338,7 +369,8 @@ fulfil reports price_list_report execute --params '{"date_from": "2024-01-01"}'
 
 ## Tips
 
-- Use `--json` to force JSON output (automatic when piped)
+- Use `--format json` to force JSON output (automatic when piped)
+- Use `--format csv` or `--format ndjson` for other machine-readable formats
 - Use `--debug` to see HTTP request/response details
 - Use `-h` on any command for help: `fulfil sales_order list -h`
 - Run `fulfil completion` to install shell completions
@@ -350,6 +382,5 @@ fulfil reports price_list_report execute --params '{"date_from": "2024-01-01"}'
 app.command(name="api")(api_cmd)
 app.command(name="completion")(completion_install)
 
-
 # Top-level aliases for frequently-used auth subcommands
 app.command(name="workspaces")(auth.workspaces)