The **KeyClient** includes a built-in **Planet Client** for managing your planets through the command line.
It communicates directly with each planet’s API and respects all normal authorisation rules — it can only perform actions your user is permitted to do.
A web interface for planet owners and users is planned, but currently these functions are limited to the **KeyClient owner**, since they rely on privileged **Artisan** commands.
#### Getting Started
1. Open the **Connect** page in your KeyClient (the same place used to link to external planets).
2. Click **Chat** to open the test interface.
3. Choose **Sign and request an API key** — this will generate and store a key locally, valid for about **60 minutes**.
4. Once authorised, you can use your terminal to run the available **Artisan Planet commands** to interact with the planet’s API.
## Usage Examples
> 💡 **Note:** The page is an evolving document and will be updated regularly.
### Posts
| Action | Example |
| --- | --- |
| List posts | `php artisan planet:posts list` |
| Show one | `php artisan planet:posts show --id=123` |
| Create | `php artisan planet:posts create --data=title="CLI Post" --data=content="From artisan"` |
| Update | `php artisan planet:posts update --data=post_id=123 --data=content="Updated content"` |
| Confirm update | `php artisan planet:posts confirm --data=post_id=123 --data=revision_id=1234` |
| Delete | `php artisan planet:posts delete --id=123` |
| Restore | `php artisan planet:posts restore --data=id=123` |
| Attach | `php artisan planet:posts attach --id=123 --data=tag_id=9` |
| Detach | `php artisan planet:posts detach --id=123 --data=tag_id=9` |
### 🧩 Post validator summary
To successfully create a post, the Planet API requires:
| Field | Required | Notes |
| --- | --- | --- |
| `title` | ✅ | string, max 255 |
| `content` | ✅ | string |
| `category_id` | ✅ | must exist in `categories.id` |
| `post_type_id` | ✅ | must exist in `post_types.id` |
| `metadata` | optional | array of ≤6 string values |
| `attached_post_ids` | optional | array of post IDs |
| plus validation rule | category must allow given post type | |
### Categories
| Action | Example |
| --- | --- |
| List categories | `php artisan planet:categories list` |
| Create | `php artisan planet:categories create --data=title="New Category" --data=about="Test category" --data=restricted=0` |
| Update | `php artisan planet:categories update --id=5 --data=about="Updated description" --data=restricted=1` |
| Rename | `php artisan planet:categories rename --id=5 --data=title="Renamed Category"` |
| List allowed post types | `php artisan planet:categories posttypes --id=5` |
| Allow post type | `php artisan planet:categories allow --id=5 --post-type-id=2` |
| Disallow post type | `php artisan planet:categories disallow --id=5 --post-type-id=2` |
| Suspend | `php artisan planet:categories suspend --id=5` |
| Unsuspend | `php artisan planet:categories unsuspend --id=5` |
| Delete | `php artisan planet:categories delete --id=5` |
| Request access | `php artisan planet:categories request --id=5` |
| Approve access | `php artisan planet:categories approve --id=5 --user-id=42` |
| Reject access | `php artisan planet:categories reject --id=5 --user-id=42` |
| Accept invite | `php artisan planet:categories accept --id=5` |
| Change user role | `php artisan planet:categories role --id=5 --user-id=42 --data=role=mod` |
| List category users | `php artisan planet:categories users --id=5` |
### Site Setttings
| Action | Example |
| --- | --- |
| Get site setting | `php artisan planet:settings get post_updates_allowed` |
| Update site setting | `php artisan planet:settings set post_updates_allowed --value=0` |
It communicates directly with each planet’s API and respects all normal authorisation rules — it can only perform actions your user is permitted to do.
A web interface for planet owners and users is planned, but currently these functions are limited to the **KeyClient owner**, since they rely on privileged **Artisan** commands.
#### Getting Started
1. Open the **Connect** page in your KeyClient (the same place used to link to external planets).
2. Click **Chat** to open the test interface.
3. Choose **Sign and request an API key** — this will generate and store a key locally, valid for about **60 minutes**.
4. Once authorised, you can use your terminal to run the available **Artisan Planet commands** to interact with the planet’s API.
## Usage Examples
> 💡 **Note:** The page is an evolving document and will be updated regularly.
### Posts
| Action | Example |
| --- | --- |
| List posts | `php artisan planet:posts list` |
| Show one | `php artisan planet:posts show --id=123` |
| Create | `php artisan planet:posts create --data=title="CLI Post" --data=content="From artisan"` |
| Update | `php artisan planet:posts update --data=post_id=123 --data=content="Updated content"` |
| Confirm update | `php artisan planet:posts confirm --data=post_id=123 --data=revision_id=1234` |
| Delete | `php artisan planet:posts delete --id=123` |
| Restore | `php artisan planet:posts restore --data=id=123` |
| Attach | `php artisan planet:posts attach --id=123 --data=tag_id=9` |
| Detach | `php artisan planet:posts detach --id=123 --data=tag_id=9` |
### 🧩 Post validator summary
To successfully create a post, the Planet API requires:
| Field | Required | Notes |
| --- | --- | --- |
| `title` | ✅ | string, max 255 |
| `content` | ✅ | string |
| `category_id` | ✅ | must exist in `categories.id` |
| `post_type_id` | ✅ | must exist in `post_types.id` |
| `metadata` | optional | array of ≤6 string values |
| `attached_post_ids` | optional | array of post IDs |
| plus validation rule | category must allow given post type | |
### Categories
| Action | Example |
| --- | --- |
| List categories | `php artisan planet:categories list` |
| Create | `php artisan planet:categories create --data=title="New Category" --data=about="Test category" --data=restricted=0` |
| Update | `php artisan planet:categories update --id=5 --data=about="Updated description" --data=restricted=1` |
| Rename | `php artisan planet:categories rename --id=5 --data=title="Renamed Category"` |
| List allowed post types | `php artisan planet:categories posttypes --id=5` |
| Allow post type | `php artisan planet:categories allow --id=5 --post-type-id=2` |
| Disallow post type | `php artisan planet:categories disallow --id=5 --post-type-id=2` |
| Suspend | `php artisan planet:categories suspend --id=5` |
| Unsuspend | `php artisan planet:categories unsuspend --id=5` |
| Delete | `php artisan planet:categories delete --id=5` |
| Request access | `php artisan planet:categories request --id=5` |
| Approve access | `php artisan planet:categories approve --id=5 --user-id=42` |
| Reject access | `php artisan planet:categories reject --id=5 --user-id=42` |
| Accept invite | `php artisan planet:categories accept --id=5` |
| Change user role | `php artisan planet:categories role --id=5 --user-id=42 --data=role=mod` |
| List category users | `php artisan planet:categories users --id=5` |
### Site Setttings
| Action | Example |
| --- | --- |
| Get site setting | `php artisan planet:settings get post_updates_allowed` |
| Update site setting | `php artisan planet:settings set post_updates_allowed --value=0` |