> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sudoiq.com/llms.txt
> Use this file to discover all available pages before exploring further.

# CLI (agentservice)

> agentservice command-line tool for agents, execute, tools, validators, and task status

The **`agentservice`** CLI is developed in the **`cli/`** directory of the **agents-api** monorepo (sibling to this docs repo as **`../cli/`**). PyPI / wheel package name: **`agentservice`**. Console script: **`agentservice`**.

## Install

From a built wheel (version in the filename may differ):

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install agentservice-0.1.1-py3-none-any.whl
```

The wheel vendors the **`agentsapi`** client and pulls runtime dependencies (`httpx`, `pydantic`, etc.).

### Optional: tab completion

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
pip install "agentservice[completion]"
eval "$(register-python-argcomplete agentservice)"
```

Add the `eval` line to `~/.bashrc` or `~/.zshrc` to persist (on zsh, load bash completion compatibility first).

## Configure

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
agentservice login
```

You will be prompted for an API key (create one under [Sudoiq settings](https://sudoiq.com/settings)).

Default API host:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
agentservice config --host sudoiq.com
# or a full URL, e.g. https://api.example.com
```

Environment variable **`AGENTSERVICE_API_KEY`**, flag **`--api-key`**, or config files **`~/.config/agentservice/config`** / **`~/.agentservice`** (`api_key=...`, `host=...`) are also supported. **`--base-url`** overrides the host for a single command.

## Agents (workflows)

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
agentservice agents list
agentservice agents create --name "My Agent"
agentservice agents modify pull <AGENT_ID>          # draft under .agentservice/modify/<ID>/workflow.yml
agentservice agents modify validate [--agent-id <AGENT_ID>]   # client-side checks before submit (ID optional if only one draft)
agentservice agents modify submit <AGENT_ID>        # publish draft as a new version (aliases: commit)
agentservice agents modify discard <AGENT_ID>       # drop local draft without publishing (aliases: trash)
```

Use **`agentservice agents modify --help`** for the full surface: inspect or edit the graph with **`list`**, **`show-node`**, **`list-edges`**, **`set-node`**, **`set-edges`**, **`patch-edges`**, or an interactive **`shell`**.

**Backward compatibility:** older one-liners are still rewritten internally—**`agentservice agents modify <AGENT_ID>`** behaves like **`pull`**, and **`--submit` / `--discard`** on that form map to **`submit`** / **`discard`**.

## Execute and wait

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
agentservice execute --agent-id AGENT_ID --input 1="Hello"
agentservice execute --agent-id AGENT_ID --agent-version 3 --input 1="Hello"
agentservice execute --agent-id AGENT_ID --input 1="Hello" --wait
agentservice execute-with-file --agent-id AGENT_ID -f file.pdf
```

**`--wait`** follows the run until a terminal state. The implementation **prefers server push (SSE)** when the bundled client supports it and **falls back** to periodic HTTP checks if streaming is unavailable (see `agentservice execute --help`).

Task inspection:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
agentservice task status --task-id TASK_ID --agent-id AGENT_ID
agentservice task status --task-id TASK_ID --agent-id AGENT_ID --wait
```

With **`--tool-handler`**, local tool execution uses your script (see demo below); that path may use polling as documented in the CLI help.

## Tools and validators

### Add a tool from JSON

Create `tools.json` with the same shape the API expects, then push:

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "tools": [
    {
      "name": "get_current_time",
      "namespace": "main",
      "description": "Return the current UTC time as ISO 8601.",
      "schema_data": {
        "type": "object",
        "properties": {},
        "required": []
      }
    }
  ]
}
```

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
agentservice tools push -f tools.json
```

Wire **local execution** for tool calls with `agentservice task status --wait --tool-handler "python your_module.py"` or use the Python client’s **`set_tools`** for streaming runs (see [Python client](/clients/python#add-a-tool)).

### Push / list

Push JSON from a file or stdin:

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
agentservice tools push -f tools.json
agentservice validators push -f validators.json
```

Export current definitions (push-compatible JSON):

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
agentservice tools list > tools.json
agentservice validators list > validators.json
```

Expected shapes: `{ "tools": [ { "name", "namespace", "description", "schema_data" }, ... ] }` and `{ "validators": [ { "name", "json_schema" }, ... ] }`.

## Demo generator

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
agentservice demo
agentservice demo -o my_demo.py
```

Generates a sample tool + validator module and prints steps to push definitions and run with a tool handler.

## Related

* [Python client](/clients/python) (same underlying API)
* [Register server tools](/tools/register-server-tools)
* [Getting started](/quickstart/getting-started)