fulfil-cli 0.1.0__tar.gz

fulfil_cli-0.1.0/PKG-INFO

@@ -0,0 +1,291 @@
+Metadata-Version: 2.4
+Name: fulfil-cli
+Version: 0.1.0
+Summary: The Fulfil CLI — primary interface for humans and AI agents
+Keywords: fulfil,cli,erp,ecommerce
+Author: Fulfil.IO
+Author-email: Fulfil.IO <hello@fulfil.io>
+License-Expression: MIT
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: orjson>=3.10.0
+Requires-Dist: keyring>=25.0.0
+Requires-Dist: platformdirs>=4.0.0
+Requires-Dist: tomli>=2.0.0 ; python_full_version < '3.11'
+Requires-Dist: tomli-w>=1.0.0
+Requires-Python: >=3.10
+Project-URL: Homepage, https://github.com/fulfilio/fulfil-cli
+Project-URL: Bug Tracker, https://github.com/fulfilio/fulfil-cli/issues
+Description-Content-Type: text/markdown
+
+# Fulfil CLI
+
+The command-line interface for [Fulfil](https://fulfil.io) — query data, manage records, run reports, and automate workflows from the terminal.
+
+## Install
+
+```bash
+# Recommended: install with uv (https://docs.astral.sh/uv/)
+uv tool install fulfil-cli
+
+# Or with pipx
+pipx install fulfil-cli
+```
+
+> **Don't have uv or pipx?** Install uv first — it's a single command:
+> `curl -LsSf https://astral.sh/uv/install.sh | sh` (macOS/Linux) or
+> `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"` (Windows).
+> Then run `uv tool install fulfil-cli`.
+
+## Getting Started
+
+```bash
+# 1. Log in to your Fulfil workspace
+fulfil auth login
+
+# 2. List sales orders
+fulfil sales_order list --fields reference,state,total_amount
+
+# 3. Count products
+fulfil product count
+
+# 4. Look up a contact
+fulfil contact list --where '{"name": "Acme Corp"}' --fields name,email
+```
+
+## Authentication
+
+The CLI stores your API key in the system keyring (macOS Keychain, GNOME Keyring, Windows Credential Locker).
+
+```bash
+# Interactive — prompts for workspace and API key
+fulfil auth login
+
+# Non-interactive
+fulfil auth login --workspace acme.fulfil.io --api-key sk_live_...
+
+# Check current auth
+fulfil auth status
+
+# List all configured workspaces
+fulfil workspaces
+
+# Switch workspace
+fulfil auth use other-workspace.fulfil.io
+
+# Log out
+fulfil auth logout
+```
+
+**Environment variables** (useful for CI/scripts):
+
+```bash
+export FULFIL_API_KEY=sk_live_...
+export FULFIL_WORKSPACE=acme.fulfil.io
+```
+
+Priority: `--token` flag > `FULFIL_API_KEY` env var > system keyring.
+
+## Working with Records
+
+Any Fulfil model name is a valid command. Each model supports: `list`, `get`, `create`, `update`, `delete`, `count`, `call`, and `describe`.
+
+### Listing records
+
+```bash
+# List with specific fields
+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 '{"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
+
+# Control page size
+fulfil sales_order list --limit 50
+
+# Paginate — the CLI prints the full command for the next page
+fulfil sales_order list --cursor <token-from-previous-response>
+```
+
+**Available filter operators:** `gt`, `gte`, `lt`, `lte`, `ne`, `in`, `not_in`, `contains`, `startswith`, `endswith`.
+
+### Getting records by ID
+
+```bash
+fulfil sales_order get 42
+fulfil sales_order get 1,2,3
+```
+
+### Creating records
+
+```bash
+# Single record
+fulfil contact create --data '{"name": "Acme Corp"}'
+
+# Multiple records at once
+fulfil contact create --data '[{"name": "Alice"}, {"name": "Bob"}]'
+```
+
+### Updating records
+
+```bash
+fulfil sales_order update 42 --data '{"comment": "Approved by finance"}'
+fulfil sales_order update 1,2,3 --data '{"state": "confirmed"}'
+```
+
+### Deleting records
+
+```bash
+fulfil sales_order delete 42         # asks for confirmation
+fulfil sales_order delete 42 --yes   # skip confirmation
+```
+
+### Counting records
+
+```bash
+fulfil product count
+fulfil sales_order count --where '{"state": "draft"}'
+```
+
+### Calling custom methods
+
+```bash
+fulfil sales_order call confirm --ids 1,2,3
+fulfil sales_order call process --ids 42 --data '{"warehouse": 1}'
+```
+
+### Exploring models
+
+```bash
+# List all models you have access to
+fulfil models
+
+# Search for models by name
+fulfil models --search shipment
+
+# See fields and endpoints for a model
+fulfil sales_order describe
+fulfil sales_order describe confirm
+```
+
+## Reports
+
+```bash
+# List available reports
+fulfil reports
+
+# Run a report with parameters
+fulfil reports price_list_report execute --params '{"date_from": "2024-01-01"}'
+
+# Interactive — prompts for each parameter
+fulfil reports price_list_report execute -i
+
+# See what parameters a report accepts
+fulfil reports price_list_report describe
+```
+
+## Raw JSON-RPC
+
+For full control, send raw JSON-RPC requests:
+
+```bash
+fulfil api '{"method": "system.version", "params": {}}'
+
+# Pipe from stdin
+echo '{"method": "model.product.count", "params": {}}' | fulfil api -
+```
+
+## Output
+
+| Context | Format |
+|---|---|
+| Terminal | Rich tables with colors |
+| Piped / redirected / CI | JSON (automatic) |
+| `--json` flag | JSON (forced) |
+
+```bash
+# Force JSON and pipe to jq
+fulfil sales_order list --fields reference,state --json | jq '.data[].reference'
+
+# Force JSON via env var
+FULFIL_JSON=1 fulfil sales_order list
+```
+
+## Configuration
+
+```bash
+fulfil config set key value
+fulfil config get key
+fulfil config list
+```
+
+Config file location: `~/.config/fulfil/config.toml`
+
+## Global Options
+
+```
+--token TEXT        API key (overrides env and keyring)
+--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
+-h, --help         Show help
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success |
+| `2` | Bad arguments |
+| `3` | Configuration error |
+| `4` | Authentication error |
+| `5` | Not found |
+| `6` | Forbidden |
+| `7` | Validation error |
+| `8` | Rate limited |
+| `9` | Server error |
+| `10` | Network error |
+
+## Shell Completion
+
+```bash
+fulfil completion   # auto-detects zsh/bash/fish
+```
+
+## AI Agent Integration
+
+The CLI is designed for programmatic use:
+
+- **JSON output by default** when stdout is piped or redirected
+- **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`
+
+See [AGENTS.md](AGENTS.md) for the full agent guide.
+
+## Development
+
+```bash
+git clone https://github.com/fulfilio/fulfil-cli.git
+cd fulfil-cli
+uv sync --dev
+pytest
+uv run ruff check .
+uv run pre-commit install
+```

fulfil_cli-0.1.0/README.md

@@ -0,0 +1,261 @@
+# Fulfil CLI
+
+The command-line interface for [Fulfil](https://fulfil.io) — query data, manage records, run reports, and automate workflows from the terminal.
+
+## Install
+
+```bash
+# Recommended: install with uv (https://docs.astral.sh/uv/)
+uv tool install fulfil-cli
+
+# Or with pipx
+pipx install fulfil-cli
+```
+
+> **Don't have uv or pipx?** Install uv first — it's a single command:
+> `curl -LsSf https://astral.sh/uv/install.sh | sh` (macOS/Linux) or
+> `powershell -c "irm https://astral.sh/uv/install.ps1 | iex"` (Windows).
+> Then run `uv tool install fulfil-cli`.
+
+## Getting Started
+
+```bash
+# 1. Log in to your Fulfil workspace
+fulfil auth login
+
+# 2. List sales orders
+fulfil sales_order list --fields reference,state,total_amount
+
+# 3. Count products
+fulfil product count
+
+# 4. Look up a contact
+fulfil contact list --where '{"name": "Acme Corp"}' --fields name,email
+```
+
+## Authentication
+
+The CLI stores your API key in the system keyring (macOS Keychain, GNOME Keyring, Windows Credential Locker).
+
+```bash
+# Interactive — prompts for workspace and API key
+fulfil auth login
+
+# Non-interactive
+fulfil auth login --workspace acme.fulfil.io --api-key sk_live_...
+
+# Check current auth
+fulfil auth status
+
+# List all configured workspaces
+fulfil workspaces
+
+# Switch workspace
+fulfil auth use other-workspace.fulfil.io
+
+# Log out
+fulfil auth logout
+```
+
+**Environment variables** (useful for CI/scripts):
+
+```bash
+export FULFIL_API_KEY=sk_live_...
+export FULFIL_WORKSPACE=acme.fulfil.io
+```
+
+Priority: `--token` flag > `FULFIL_API_KEY` env var > system keyring.
+
+## Working with Records
+
+Any Fulfil model name is a valid command. Each model supports: `list`, `get`, `create`, `update`, `delete`, `count`, `call`, and `describe`.
+
+### Listing records
+
+```bash
+# List with specific fields
+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 '{"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
+
+# Control page size
+fulfil sales_order list --limit 50
+
+# Paginate — the CLI prints the full command for the next page
+fulfil sales_order list --cursor <token-from-previous-response>
+```
+
+**Available filter operators:** `gt`, `gte`, `lt`, `lte`, `ne`, `in`, `not_in`, `contains`, `startswith`, `endswith`.
+
+### Getting records by ID
+
+```bash
+fulfil sales_order get 42
+fulfil sales_order get 1,2,3
+```
+
+### Creating records
+
+```bash
+# Single record
+fulfil contact create --data '{"name": "Acme Corp"}'
+
+# Multiple records at once
+fulfil contact create --data '[{"name": "Alice"}, {"name": "Bob"}]'
+```
+
+### Updating records
+
+```bash
+fulfil sales_order update 42 --data '{"comment": "Approved by finance"}'
+fulfil sales_order update 1,2,3 --data '{"state": "confirmed"}'
+```
+
+### Deleting records
+
+```bash
+fulfil sales_order delete 42         # asks for confirmation
+fulfil sales_order delete 42 --yes   # skip confirmation
+```
+
+### Counting records
+
+```bash
+fulfil product count
+fulfil sales_order count --where '{"state": "draft"}'
+```
+
+### Calling custom methods
+
+```bash
+fulfil sales_order call confirm --ids 1,2,3
+fulfil sales_order call process --ids 42 --data '{"warehouse": 1}'
+```
+
+### Exploring models
+
+```bash
+# List all models you have access to
+fulfil models
+
+# Search for models by name
+fulfil models --search shipment
+
+# See fields and endpoints for a model
+fulfil sales_order describe
+fulfil sales_order describe confirm
+```
+
+## Reports
+
+```bash
+# List available reports
+fulfil reports
+
+# Run a report with parameters
+fulfil reports price_list_report execute --params '{"date_from": "2024-01-01"}'
+
+# Interactive — prompts for each parameter
+fulfil reports price_list_report execute -i
+
+# See what parameters a report accepts
+fulfil reports price_list_report describe
+```
+
+## Raw JSON-RPC
+
+For full control, send raw JSON-RPC requests:
+
+```bash
+fulfil api '{"method": "system.version", "params": {}}'
+
+# Pipe from stdin
+echo '{"method": "model.product.count", "params": {}}' | fulfil api -
+```
+
+## Output
+
+| Context | Format |
+|---|---|
+| Terminal | Rich tables with colors |
+| Piped / redirected / CI | JSON (automatic) |
+| `--json` flag | JSON (forced) |
+
+```bash
+# Force JSON and pipe to jq
+fulfil sales_order list --fields reference,state --json | jq '.data[].reference'
+
+# Force JSON via env var
+FULFIL_JSON=1 fulfil sales_order list
+```
+
+## Configuration
+
+```bash
+fulfil config set key value
+fulfil config get key
+fulfil config list
+```
+
+Config file location: `~/.config/fulfil/config.toml`
+
+## Global Options
+
+```
+--token TEXT        API key (overrides env and keyring)
+--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
+-h, --help         Show help
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|---|---|
+| `0` | Success |
+| `2` | Bad arguments |
+| `3` | Configuration error |
+| `4` | Authentication error |
+| `5` | Not found |
+| `6` | Forbidden |
+| `7` | Validation error |
+| `8` | Rate limited |
+| `9` | Server error |
+| `10` | Network error |
+
+## Shell Completion
+
+```bash
+fulfil completion   # auto-detects zsh/bash/fish
+```
+
+## AI Agent Integration
+
+The CLI is designed for programmatic use:
+
+- **JSON output by default** when stdout is piped or redirected
+- **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`
+
+See [AGENTS.md](AGENTS.md) for the full agent guide.
+
+## Development
+
+```bash
+git clone https://github.com/fulfilio/fulfil-cli.git
+cd fulfil-cli
+uv sync --dev
+pytest
+uv run ruff check .
+uv run pre-commit install
+```

fulfil_cli-0.1.0/pyproject.toml

@@ -0,0 +1,117 @@
+[build-system]
+requires = ["uv_build>=0.10.4,<0.11.0"]
+build-backend = "uv_build"
+
+[project]
+name = "fulfil-cli"
+version = "0.1.0"
+description = "The Fulfil CLI — primary interface for humans and AI agents"
+readme = "README.md"
+requires-python = ">=3.10"
+license = "MIT"
+authors = [{ name = "Fulfil.IO", email = "hello@fulfil.io" }]
+keywords = ["fulfil", "cli", "erp", "ecommerce"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = [
+    "typer>=0.12.0",
+    "rich>=13.0.0",
+    "httpx>=0.27.0",
+    "orjson>=3.10.0",
+    "keyring>=25.0.0",
+    "platformdirs>=4.0.0",
+    "tomli>=2.0.0; python_version < '3.11'",
+    "tomli-w>=1.0.0",
+]
+
+[project.scripts]
+fulfil = "fulfil_cli.cli:main"
+
+[project.urls]
+Homepage = "https://github.com/fulfilio/fulfil-cli"
+"Bug Tracker" = "https://github.com/fulfilio/fulfil-cli/issues"
+
+[dependency-groups]
+dev = [
+    "pytest>=8.0.0",
+    "pytest-httpx>=0.30.0",
+    "pytest-cov>=6.0.0",
+    "coverage[toml]>=7.0.0",
+    "ruff>=0.4.0",
+    "pre-commit>=3.7.0",
+]
+
+[tool.uv.build-backend]
+module-name = "fulfil_cli"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["src"]
+addopts = [
+    "--strict-markers",
+    "--strict-config",
+    "-ra",
+]
+xfail_strict = true
+
+[tool.ruff]
+target-version = "py310"
+line-length = 100
+
+[tool.ruff.lint]
+select = [
+    "E",    # pycodestyle errors
+    "W",    # pycodestyle warnings
+    "F",    # pyflakes
+    "I",    # isort
+    "N",    # pep8-naming
+    "UP",   # pyupgrade
+    "B",    # flake8-bugbear
+    "C4",   # flake8-comprehensions
+    "SIM",  # flake8-simplify
+    "RUF",  # ruff-specific
+    "PTH",  # flake8-use-pathlib
+    "PERF", # perflint
+    "ISC",  # implicit-str-concat
+]
+ignore = [
+    "B008",   # function-call-in-default-argument — Typer uses this pattern
+    "ISC001", # conflicts with ruff formatter
+]
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "S101",  # allow assert
+]
+
+[tool.ruff.lint.isort]
+known-first-party = ["fulfil_cli"]
+
+[tool.coverage.run]
+source = ["fulfil_cli"]
+branch = true
+parallel = true
+
+[tool.coverage.report]
+show_missing = true
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+    "@(abc\\.)?abstractmethod",
+]
+
+[tool.coverage.paths]
+source = [
+    "src/",
+    "*/site-packages/",
+]

fulfil_cli-0.1.0/src/fulfil_cli/__init__.py

@@ -0,0 +1,3 @@
+"""Fulfil CLI — primary interface for humans and AI agents."""
+
+__version__ = "0.1.0"

fulfil_cli-0.1.0/src/fulfil_cli/__main__.py

@@ -0,0 +1,5 @@
+"""Allow running as `python -m fulfil_cli`."""
+
+from fulfil_cli.cli import main
+
+main()