Version: 0.5

gest artifact

Create, update, list, and manage artifacts. Artifacts store documents such as specs, ADRs, RFCs, and notes alongside your project.

Usage

gest artifact <COMMAND> [OPTIONS]

Subcommands

Command	Aliases	Description
`archive`		Archive an artifact
`create`	`new`	Create a new artifact
`delete`	`rm`	Delete an artifact and its dependent rows
`list`	`ls`	List artifacts with optional filters
`show`	`view`	Display an artifact's full details
`update`	`edit`	Update an artifact's fields
`tag`		Add tags to an artifact
`untag`		Remove tags from an artifact
`meta`		Read or write metadata fields
`note`		Manage notes attached to an artifact

artifact archive

Move an artifact to the archive by setting its archived_at timestamp.

gest artifact archive [OPTIONS] <ID>

Arguments

Argument	Description
`<ID>`	Artifact ID or unique prefix

Options

Flag	Description
`-j, --json`	Output as JSON
`-q, --quiet`	Print only the artifact ID

Examples

gest artifact archive abc123

artifact create

Create a new artifact from inline text, a source file, an editor, or stdin.

When --body and --source are both omitted and stdin is a terminal, $EDITOR opens for interactive editing. When stdin is a pipe, the piped content is used as the body.

gest artifact create [OPTIONS] [TITLE]

Arguments

Argument	Description
`[TITLE]`	Artifact title (auto-extracted from the first `#` heading when piping stdin or `--source`)

Options

Flag	Description
`--batch`	Read NDJSON from stdin (one artifact per line)
`-b, --body <BODY>`	Body content as an inline string (skips editor and stdin)
`-i, --iteration <ITERATION>`	Add the artifact to an iteration (ID or prefix)
`-j, --json`	Output the created artifact as JSON
`-m, --metadata <KEY=VALUE>`	Set a metadata key=value pair (repeatable; supports dot-paths and scalar inference)
`--metadata-json <JSON>`	Merge a JSON object into metadata (repeatable; applied after `--metadata` pairs)
`-q, --quiet`	Print only the artifact ID
`-s, --source <SOURCE>`	Read body content from a file path
`-t, --tag <TAG>`	Tag (repeatable). Use tags like `spec`, `adr`, `rfc`, `note` to categorize.

Artifact categorization is tag-driven in v0.5.0. The --type/-k flag and kind field were removed — tag your artifacts with spec, adr, rfc, etc. and filter listings with --tag.

Examples

# Create from inline body
gest artifact create "Auth Spec" --tag spec --body "## Overview\nAuth flow details..."

# Create from a file (title extracted from the first heading)
gest artifact create --tag adr --source docs/decisions/001-storage.md

# Create interactively (opens $EDITOR)
gest artifact create "My RFC" --tag rfc --tag backend --tag v2

# Add to an iteration
gest artifact create "Sprint 3 Notes" --tag note -i iter123

# Pipe body from stdin
echo "# My Spec\nDetails..." | gest artifact create --tag spec

# Batch-create artifacts from NDJSON
cat artifacts.ndjson | gest artifact create --batch

# Machine-readable output
gest artifact create "Quick note" --tag note --json
gest artifact create "Quick note" --tag note -q

artifact delete

Permanently delete an artifact and its dependent rows (tags, metadata, notes, links). This is irreversible; prefer archive when you only want to hide an artifact from active listings.

gest artifact delete [OPTIONS] <ID>

Arguments

Argument	Description
`<ID>`	Artifact ID or unique prefix

Options

Flag	Description
`--yes`	Skip the interactive confirmation prompt
`--force`	Reserved for future guards; currently a no-op (artifacts have no guards today)
`-j, --json`	Output as JSON
`-q, --quiet`	Suppress normal output

Examples

# Interactive (prompts for confirmation)
gest artifact delete abc123

# Non-interactive (scripts, CI)
gest artifact delete abc123 --yes

artifact list

List artifacts, optionally filtered by tag or archive status.

gest artifact list [OPTIONS]

Options

Flag	Description
`-a, --all`	Include archived artifacts alongside active ones
`--archived`	Show only archived artifacts
`-j, --json`	Output as JSON
`-t, --tag <TAG>`	Filter by tag

Examples

# List active artifacts
gest artifact list

# Filter by tag (use category tags like `spec`, `adr`, `rfc`)
gest artifact list --tag spec

# Include archived
gest artifact list --all

# JSON output for scripting
gest artifact list --json

artifact show

Display an artifact's full details and rendered body.

gest artifact show [OPTIONS] <ID>

Arguments

Argument	Description
`<ID>`	Artifact ID or unique prefix

Options

Flag	Description
`-j, --json`	Output as JSON instead of formatted detail

Examples

gest artifact show abc123
gest artifact show abc123 --json

artifact update

Update an artifact's title, body, metadata, or tags.

gest artifact update [OPTIONS] <ID>

Arguments

Argument	Description
`<ID>`	Artifact ID or unique prefix

Options

Flag	Description
`-b, --body <BODY>`	Replace the body content
`-e, --edit`	Open `$EDITOR` pre-filled with the current body
`-j, --json`	Output as JSON
`-m, --metadata <KEY=VALUE>`	Set a metadata key=value pair (repeatable; supports dot-paths and scalar inference)
`--metadata-json <JSON>`	Merge a JSON object into metadata (repeatable; applied after `--metadata` pairs)
`-q, --quiet`	Print only the artifact ID
`-t, --tag <TAG>`	Replace all tags (repeatable)
`-T, --title <TITLE>`	New title

Examples

gest artifact update abc123 -T "Updated Title"
gest artifact update abc123 --tag approved --tag backend

# Machine-readable output
gest artifact update abc123 -T "New Title" --json

artifact tag

Add tags to an artifact, deduplicating with any existing tags.

gest artifact tag [OPTIONS] <ID> [TAGS]...

Arguments

Argument	Description
`<ID>`	Artifact ID or unique prefix
`[TAGS]...`	Tags to add (space or comma-separated)

Options

Flag	Description
`-j, --json`	Output the artifact as JSON after tagging
`-q, --quiet`	Output only the artifact ID

Examples

gest artifact tag abc123 approved reviewed
gest artifact tag abc123 approved,reviewed

artifact untag

Remove tags from an artifact.

gest artifact untag [OPTIONS] <ID> [TAGS]...

Arguments

Argument	Description
`<ID>`	Artifact ID or unique prefix
`[TAGS]...`	Tags to remove (space or comma-separated)

Options

Flag	Description
`-j, --json`	Output the artifact as JSON after untagging
`-q, --quiet`	Output only the artifact ID

Examples

gest artifact untag abc123 draft

artifact meta

Read or write artifact metadata fields. Metadata uses dot-delimited key paths for nested values.

gest artifact meta <COMMAND>

meta get

Retrieve a single metadata value.

gest artifact meta get [OPTIONS] <ID> <PATH>

Argument	Description
`<ID>`	Artifact ID or unique prefix
`<PATH>`	Dot-delimited key path (e.g. `outer.inner`)

Flag	Description
`--json`	Output as a JSON object
`--raw`	Output the bare value with no styling

meta set

Set a metadata value. Strings, numbers, booleans, and null are auto-detected.

gest artifact meta set [OPTIONS] <ID> <PATH> <VALUE>

Argument	Description
`<ID>`	Artifact ID or unique prefix
`<PATH>`	Dot-delimited key path (e.g. `config.timeout`)
`<VALUE>`	Value to set

Flag	Description
`-j, --json`	Output as JSON
`-q, --quiet`	Print only the entity ID

Examples

# Set a metadata field
gest artifact meta set abc123 status "approved"

# Read it back
gest artifact meta get abc123 status

# JSON output
gest artifact meta get abc123 status --json

# Raw value (no styling)
gest artifact meta get abc123 status --raw

artifact note

Manage notes attached to an artifact. Notes are lightweight markdown bodies that hang off an artifact and are a good fit for running commentary, review threads, or agent annotations that should live alongside the artifact without altering its body.

gest artifact note <COMMAND>

note add

Add a new note to an artifact. Use --body - to open $EDITOR for interactive entry.

gest artifact note add [OPTIONS] --body <BODY> <ID>

Argument	Description
`<ID>`	Artifact ID or unique prefix

Flag	Description
`-b, --body <BODY>`	Note body (required; use `-` to open `$EDITOR`)
`--agent <AGENT>`	Set the author (agent) identifier for this note
`-j, --json`	Output as JSON
`-q, --quiet`	Print only the note ID

note list

List all notes attached to an artifact, newest first.

gest artifact note list [OPTIONS] <ID>

Argument	Description
`<ID>`	Artifact ID or unique prefix

Flag	Description
`--limit <N>`	Cap the number of items returned
`-j, --json`	Output as JSON
`-q, --quiet`	Print only note IDs

note show

Display a single note.

gest artifact note show [OPTIONS] <ID>

Argument	Description
`<ID>`	Note ID or unique prefix

Flag	Description
`-j, --json`	Output as JSON

note update

Replace a note's body.

gest artifact note update [OPTIONS] <ID>

Argument	Description
`<ID>`	Note ID or unique prefix

Flag	Description
`-b, --body <BODY>`	New body text (use `-` to open `$EDITOR`)
`-j, --json`	Output as JSON
`-q, --quiet`	Print only the note ID

note delete

Delete a note from an artifact.

gest artifact note delete [OPTIONS] <ID>

Argument	Description
`<ID>`	Note ID or unique prefix

Flag	Description
`--yes`	Skip the interactive confirmation prompt
`-j, --json`	Output as JSON
`-q, --quiet`	Suppress normal output

Examples

# Add a note inline
gest artifact note add abc123 --body "Reviewed by security team; approved."

# Add a note via $EDITOR
gest artifact note add abc123 --body -

# Attribute a note to an agent
gest artifact note add abc123 --body "Drafted outline" --agent implement-agent

# List notes for an artifact
gest artifact note list abc123
gest artifact note list abc123 --limit 5 --json

# Show and update a single note
gest artifact note show note456
gest artifact note update note456 --body "Updated commentary"

# Delete a note (non-interactive)
gest artifact note delete note456 --yes

Usage​

Subcommands​

artifact archive​

Arguments​

Options​

Examples​

artifact create​

Arguments​

Options​

Examples​

artifact delete​

Arguments​

Options​

Examples​

artifact list​

Options​

Examples​

artifact show​

Arguments​

Options​

Examples​

artifact update​

Arguments​

Options​

Examples​

artifact tag​

Arguments​

Options​

Examples​

artifact untag​

Arguments​

Options​

Examples​

artifact meta​

meta get​

meta set​

Examples​

artifact note​

note add​

note list​

note show​

note update​

note delete​

Examples​

Usage

Subcommands

artifact archive

Arguments

Options

Examples

artifact create

Arguments

Options

Examples

artifact delete

Arguments

Options

Examples

artifact list

Options

Examples

artifact show

Arguments

Options

Examples

artifact update

Arguments

Options

Examples

artifact tag

Arguments

Options

Examples

artifact untag

Arguments

Options

Examples

artifact meta

meta get

meta set

Examples

artifact note

note add

note list

note show

note update

note delete

Examples