Metadata-Version: 2.4
Name: keystone-cli
Version: 0.5.0
Summary: Keystone CLI — build, test, deploy and operate pro-code agents, and manage knowledge bases, prompts, tool credentials and skills on the Keystone platform.
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Environment :: Console
Classifier: Operating System :: OS Independent
Requires-Python: >=3.12
Description-Content-Type: text/markdown
Requires-Dist: keystone-agent-sdk<0.14,>=0.13.27
Requires-Dist: keystone-request-context<0.4,>=0.3
Requires-Dist: typer<1,>=0.12
Requires-Dist: httpx<1,>=0.27
Requires-Dist: truststore<1,>=0.10
Requires-Dist: pytest<9,>=8
Provides-Extra: dev
Requires-Dist: pytest<9,>=8; extra == "dev"
Requires-Dist: pytest-cov<7,>=6; extra == "dev"
Requires-Dist: ruff==0.15.15; extra == "dev"

# keystone-cli

`keystone` is the command-line tool of the Keystone platform. Use it to build, test, deploy and operate
pro-code agents. You can also manage knowledge bases, prompts, tool credentials and skills with it.

The CLI includes the Keystone agent SDK (`keystone-agent-sdk`). An agent project that you create with
the CLI uses that SDK.

## Install

The CLI needs Python 3.12 or later.

```bash
pip install keystone-cli
keystone --version
```

## Get started

1. Log in. The command opens your browser and keeps your session for later commands.

   ```bash
   keystone login
   ```

2. Select the workspace that your commands use.

   ```bash
   keystone workspace use <name>
   ```

3. Create an agent project from a template, then check it.

   ```bash
   keystone agent init my-agent --template llm
   keystone agent validate my-agent
   ```

4. Run the unit tests of the agent on your computer.

   ```bash
   keystone agent test my-agent
   ```

5. Deploy the agent, make the new version Live, and call it.

   ```bash
   keystone agent deploy my-agent --publish --wait
   keystone agent invoke my-agent --input '{"prompt": "hi"}'
   ```

To see the fields of `agent.yaml`, run `keystone agent manifest`. Every command has `--help`.

## CI with a service account

Use a platform service account in CI. The CLI sends its API key as `Authorization: Bearer <key>`.
A CI job does not run `keystone login`.

Before you start, an admin gives the service account three permissions on its workspace, one time:

| Permission | Resource | Why |
| --- | --- | --- |
| `agent:register` | the workspace of the service account | Register a new agent |
| `agent-vb:version:create` | the workspace of the service account | Upload a bundle |
| `agent:read` | the workspace of the service account | Find an agent by name (`delete`, `versions`, `status` and others) |

In the portal, open **Settings → Service Accounts**, open the access dialog of the account, and
select **This workspace** as the resource.

`deploy --publish`, `invoke`, `runs` and `threads` work without `agent:read` on the workspace. A
service account can not read agent logs: `keystone agent logs` needs `trace:read`, which only a user
can hold.

When the service account deploys a new agent, it gets all other permissions on that agent
automatically: read, invoke, and version create, deploy, publish and retire. To invoke an agent that
another user created, an admin must give `agent:invoke` on that agent.

Set these variables in the CI job:

| Variable | Value |
| --- | --- |
| `KEYSTONE_API_KEY` | The API key of the service account. Keep it in a masked CI secret. |
| `KEYSTONE_WORKSPACE_ID` | The UUID of the target workspace. |
| `KEYSTONE_API_BASE` | Optional. The platform API URL. The default is the URL of your CLI package. |
| `KEYSTONE_AGENT_API_BASE` | Optional. The agent API URL for `invoke`, `runs` and `threads`. |

Then do these steps:

1. Make sure that the CLI uses the service account.

   ```bash
   export KEYSTONE_API_KEY=<sa-api-key>
   export KEYSTONE_WORKSPACE_ID=<workspace-uuid>
   keystone whoami
   ```

2. Deploy the agent.

   ```bash
   keystone agent deploy my-agent --publish --wait
   ```

3. Call the agent.

   ```bash
   keystone agent invoke my-agent --input '{"prompt": "ping"}'
   ```

Do not put the API key on the command line. The shell history and the CI log can show it.

These rules apply when `KEYSTONE_API_KEY` is set:

- The key has priority over `KEYSTONE_TOKEN` and over a saved login.
- The CLI does not save the key to a file, and it does not show the key.
  `keystone whoami` shows only the key ID.
- The CLI does not select a workspace for you. `--workspace-id` has priority over `KEYSTONE_WORKSPACE_ID`.
  `KEYSTONE_WORKSPACE_ID` has priority over the saved workspace.
- `keystone workspace list` and `keystone workspace use` do not operate with a key.

## Commands

| Command | What it does |
| --- | --- |
| `keystone login`, `keystone whoami` | Log in, and show your user. |
| `keystone workspace` | List and select the workspace that your commands use. |
| `keystone agent` | Develop and test an agent locally (`init`, `validate`, `run`, `test`, `manifest`), ship it (`deploy`, `publish`, `status`, `retire`, `delete`), and operate and debug it (`invoke`, `logs`, `fetch`, `doctor`, `runs`, `hitl`, `traces`, `threads`). |
| `keystone dev` | Run the graph of the agent locally again each time you save a file. |
| `keystone kb` | Create and manage knowledge bases. |
| `keystone prompt` | Manage the prompts of a workspace. |
| `keystone tool-credentials` | Manage the credentials that the catalogue tools of your agents use. |
| `keystone skills` | Install Claude Code skills for work on agents. |
| `keystone version` | Show the CLI version, the target environment and the version of the bundled agent SDK. |

## When a run fails

Start with this command. It shows the steps, the errors and the logs of one run.

```bash
keystone agent runs debug <agent> <run_id>
```
