clua 0.1.0__py3-none-any.whl

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
clua/__init__.py ADDED
@@ -0,0 +1,22 @@
1
+ from importlib.metadata import version
2
+ from importlib.resources import files
3
+
4
+ from xiii_cli_core.config import Product, Surface
5
+ from xiii_cli_core.main import build_app, run
6
+
7
+ PRODUCT = Product(
8
+ name="clua",
9
+ display_name="Clua",
10
+ api_url="https://api.clua.nulara.de/v1/app",
11
+ oauth_client_id="clua-cli",
12
+ manifest=files(__name__).joinpath("spec.json"),
13
+ version=version("clua"),
14
+ skill=files(__name__).joinpath("skill/SKILL.md"),
15
+ )
16
+
17
+
18
+ def main() -> None:
19
+ run(lambda: build_app(PRODUCT, Surface.CUSTOMER))
20
+
21
+
22
+ __all__ = ["PRODUCT", "main"]
clua/skill/SKILL.md ADDED
@@ -0,0 +1,74 @@
1
+ ---
2
+ name: clua
3
+ description: Work in a Clua workspace through the `clua` command-line tool. Use when the user asks to read, create or change tasks, projects, companies, contacts, deals, time entries, calendar events, knowledge articles or other Clua data, or to read anything from their Clua workspace.
4
+ ---
5
+
6
+ # Clua CLI
7
+
8
+ `clua` calls the Clua API for the workspace the user signed in to. Every
9
+ product module is a command group (`clua tasks …`, `clua time-entries …`)
10
+ whose commands mirror the API one to one.
11
+
12
+ ## Rules
13
+
14
+ - Pass `--json` to every command. Data goes to stdout as one JSON document; a
15
+ failure is one JSON object on stderr and a non-zero exit code. Never parse
16
+ the human output.
17
+ - A command that changes data refuses to run without `--yes` outside a
18
+ terminal. Before the first change, show the user what you will do; run the
19
+ same command with `--dry-run` to print the request without sending it.
20
+ - Never guess a command or option. Ask the CLI:
21
+ - `clua describe` lists the modules and their commands,
22
+ - `clua describe <module>` lists one module's commands,
23
+ - `clua describe <module> <command>` prints arguments, options, the
24
+ request schema, required fields and an example command line.
25
+ - A list that pages takes `--all` and then prints `{"items": […], "total": n}`;
26
+ add `--max-items N` to stop early. Without `--all` you get one page.
27
+ - A field whose value is JSON, or a whole body, can be passed as a file with
28
+ `--input body.json` (or `--input -` for stdin) instead of single options.
29
+ - A command that returns a file (an export, an attachment) needs
30
+ `--output <path>`; with `--json` it reports where the file went.
31
+ - `clua.nulara.de` runs without a language model. `clua agent run` and the
32
+ `agents`, `skills` and `threads` commands answer 404 there; you are the
33
+ model, so use the typed commands.
34
+
35
+ ## Sign in
36
+
37
+ Check first: `clua doctor --json`. Exit 0 means ready. Exit 3 means the user
38
+ has to sign in; ask them to run `clua login` themselves (it opens a browser
39
+ for their consent). In CI the environment variable `CLUA_API_TOKEN` holds an
40
+ API key instead. `clua workspace use <name>` switches between workspaces the
41
+ user signed in to; `--workspace <name>` overrides it for one command.
42
+
43
+ ## Exit codes
44
+
45
+ | Exit | `error` | What to do |
46
+ | ---- | ---------------------- | ---------------------------------------------------------- |
47
+ | 0 | | Success |
48
+ | 1 | `runtime_error` | Read `message`; often a missing `--yes` |
49
+ | 2 | `configuration_error` | Configuration or workspace selection is wrong |
50
+ | 3 | `authentication_error` | Ask the user to run `clua login` |
51
+ | 4 | `authorization_error` | The user or key lacks the right; tell the user |
52
+ | 5 | `api_error` | The API refused; `code` names why, `detail` has the fields |
53
+ | 9 | `usage_error` | The command line was wrong; check `describe` |
54
+ | 10 | `network_error` | The API was unreachable; retry later |
55
+ | 11 | `rate_limit_error` | Wait `retry_after` seconds, then retry |
56
+
57
+ Reads are retried on network errors and server errors already, and every
58
+ request on a rate limit, so do not wrap commands in your own retry loop.
59
+ A 422 `api_error` lists the invalid fields in `detail`; fix them and send the
60
+ command again.
61
+
62
+ ## Common work
63
+
64
+ ```console
65
+ clua tasks list --all --json
66
+ clua tasks create --title "Angebot nachfassen" --project-id <project-id> --yes --json
67
+ clua time-entries start-timer --dry-run --json
68
+ clua time-entries get-timesheet --week-start 2026-11-23 --json
69
+ clua companies list --search "<name>" --json
70
+ clua deals list --all --json
71
+ ```
72
+
73
+ Check every option with `clua describe <module> <command>` before the first
74
+ call; the examples above only show the shape.